Hosting Options
When the Transport property is set to ttHTTP, the MCPServer component may be hosted via an external server framework like ASP.NET Core, via an embedded HTTP server, or in a fully offline mode. The ProcessingMode property should be set according to the type of hosting option used. Possible hosting options are:
The following aspects of component use and behavior are impacted by hosting options:
- Processing Inbound Requests
- Authentication
- Configuration Requirements
- Connection Security
- Sending Responses
Embedded Server
Processing Inbound Requests
When functioning in embedded server mode, the component's StartListening method causes the embedded web server to begin listening for inbound MCP requests. The LocalHost and LocalPort fields must be set prior to starting the server.
if (procmode == MCPServerProcessingModes.modeEmbeddedServer)
{
server.ServerSettings.LocalHost = "localhost";
server.ServerSettings.LocalPort = "80";
server.StartListening();
}
The StopListening method disconnects any connected clients and stops listening.
Configuration Requirements
The embedded server's behavior is configured via the ServerSettings property and the ServerCert property. These settings control the local interface and port on which the server listens, as well as the allowed authentication methods.
Authentication
When hosting MCPServer using the embedded web server, the AllowedAuthMethods field determines which authentication schemes the embedded server will allow.
Connection Security
When using the embedded server, the server hosts a plaintext (HTTP) endpoint by default. The ServerCert property is used to enable TLS for secure connections. When ServerCert is set to a TLS certificate, the embedded HTTP server will use and require TLS for inbound HTTPS connections.
Sending Responses
The type of HTTP response generated by the component depends on logic that occurs within events that fire as the component processes requests.
After processing a request, the component automatically sends an HTTP response according to the MCP standard. Errors are reported to the client via HTTP error responses, and success is reported via 200 OK. The contents of the response depend on the specific operation performed.
External Server
Processing Inbound Requests
When functioning in external server mode, the external server framework listens for HTTP requests. The HttpContext object must be passed explicitly to the component to process the request.
The following is a set of simple examples showing how MCP SDK can be used with various external server frameworks.
ASP.NET Core
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Run(async context =>
{
if (context.Request.Path.StartsWithSegments("/server"))
{
// The external validation logic is represented abstractly by VerifyAuth.
bool authenticationSuccessful = VerifyAuth(context.Request.Headers["Authorization"]);
if (authenticationSuccessful)
{
server.ProcessRequest(context);
}
}
});
ASP.NET (Classic)
In ASP.NET, the path can be inspected from within the Application_PostAuthorizeRequest event, and the ProcessRequest method can be called within this event.
MCPServer server = null;
void Application_PostAuthorizeRequest(object sender, EventArgs e)
{
if (HttpContext.Current.Request.Path.StartsWith("/server"))
{
if (server == null)
{
server = new MCPServer();
}
HttpContext context = HttpContext.Current;
server.ProcessRequest(context);
// Prevent the ExtensionlessUrl handler from sending the request for the second time.
CompleteRequest();
}
}
Route and Handler
public static class RouteConfig
{
public static void RegisterRoutes(RouteCollection routes)
{
Route route = new Route("server", new ServerRouteHandler());
routes.Add("Server", route);
}
}
public class ServerHandler : System.Web.IHttpHandler
{
MCPServer server;
public ServerHandler()
{
server = new MCPServer();
}
public void ProcessRequest(HttpContext context)
{
server.ProcessRequest(context);
}
public bool IsReusable
{
get
{
// Allows another request to use the same IHttpHandler instance.
return true;
}
}
}
public class ServerRouteHandler : System.Web.Routing.IRouteHandler
{
ServerHandler handler = new ServerHandler();
public IHttpHandler GetHttpHandler(RequestContext requestContext)
{
return handler;
}
}
void Application_Start(object sender, EventArgs e)
{
// Code that runs on application startup.
// This registration is needed to have the handler called when there is a request.
RouteConfig.RegisterRoutes(RouteTable.Routes);
}
Authentication
Authentication occurs outside the scope of MCP SDK when using the external server mode. Prior to passing the HttpContext to the component via ProcessRequest, the incoming request should be authenticated using the appropriate mechanism. For instance, an ASP.NET Core application may require basic or NTLM authentication to access the endpoint where the request will be processed. Once the request has been authenticated through external verification, the HttpContext should be passed to the ProcessRequest method.
Configuration Requirements
External servers may require configuration such that MCP requests can be passed to MCP SDK. The details depend on the framework used to build the external server.
ASP.NET Core
When building the services list, ensure that no service blocks requests with certain verbs from being passed forward. The REST API of the server uses all standard HTTP verbs, defined in the HTTP 1.1 specification.
ASP.NET Framework
Often, ASP.NET projects by default use handlers that do not support the full range of HTTP verbs that are required by MCPServer. The full list of verbs can be found below.
- GET
- POST
- PUT
ASP.NET has two modes, Integrated and Classic, that can be selected depending on the requirements of the project.
If the classic mode is selected, then the ISAPI handler will need to be configured. The specific handler depends on whether the project is running in a 32-bit or 64-bit environment. Additionally, to make sure that the application runs without issue, the Web.config needs to disable the validation check that checks that the integrated mode is being used.
If the integrated mode (32- or 64-bit) is selected, then the Integrated handler will need to be configured.
Connection Security
When hosting the component via an external server, the security settings in the external server framework determine connection security. The component has no impact on TLS in this processing mode.
Sending Responses
The type of HTTP response generated by the component depends on logic that occurs within events that fire as the component processes requests.
After processing a request, the component populates the properties of the HttpContext with the status code, headers, and body that should be included in the HTTP response. The properties in this context are then automatically used to generate and send an HTTP response to the client, without requiring any further action by the component.
Offline Mode
Processing Inbound Requests
When functioning in offline mode, the component uses the Request and RequestHeaders properties to read inbound requests. These properties should be set to the request body and headers, respectively, before processing the request by calling the ProcessRequest method with a null HttpContext parameter.
In offline mode, the component will not attempt to send a response to clients. Instead, the Response and ResponseHeaders properties are set to the body content and headers, respectively, of the response.
Authentication
Authentication is fully outside the scope of the component when using offline mode. The component will process requests without any direct checks for authentication.
Configuration Requirements
In offline mode, the component is agnostic to any process that occurs prior to setting the Request and RequestHeaders properties, and as such does not require any additional configuration.
Connection Security
In offline mode, the component does not have a live connection to a client, so connection security is not directly relevant to the component's operation.
Sending Responses
The type of HTTP response generated by the component depends on logic that occurs within events that fire as the component processes requests.
After processing a request in offline mode, the component will populate the Response and ResponseHeaders properties with the content of the response. This data can be extracted from these properties and returned to the client using whatever approach is appropriate.