.NET MCP桥接工具

Getting Started

Docker Support

You can run the bridge server in a Docker container:

docker build -t mcp-bridge -f McpPlugin.Server/Dockerfile .
docker run -p 8080:8080 mcp-bridge port=8080 client-transport=http

Configuration Reference

MCP Plugin for .NET

1. The Server (`McpPlugin.Server`)

The server acts as a hub. You can run the provided DemoWebApp or host it in your own ASP.NET Core application.

Running the Demo Server:

cd DemoWebApp
dotnet run port=11111 client-transport=stdio

Note: Use client-transport=stdio if connecting from Claude Desktop, or client-transport=http for HTTP-based clients.

Hosting in your own Web App:

// Program.cs
using com.IvanMurzak.McpPlugin.Common;
using com.IvanMurzak.McpPlugin.Common.Utils;
using com.IvanMurzak.McpPlugin.Server;

var builder = WebApplication.CreateBuilder(args);

// 1. Prepare arguments (or load from config)
var dataArguments = new DataArguments(args);

// 2. Register MCP Server services
builder.Services
    .WithMcpServer(dataArguments) // Configures transport based on dataArguments.ClientTransport
    .WithMcpPluginServer(dataArguments);

// 3. Configure Kestrel with separate IPv4/IPv6 bindings (avoids dual-stack issues on macOS)
builder.WebHost.UseKestrelForMcpPlugin(dataArguments.Port);

var app = builder.Build();

// 4. Use MCP Server middleware
app.UseMcpPluginServer(dataArguments);

app.Run();

2. The Client App (`McpPlugin`)

Add the com.IvanMurzak.McpPlugin package to your .NET application.

Defining Tools, Prompts, and Resources:

using com.IvanMurzak.McpPlugin;
using System.ComponentModel;

[McpPluginToolType]
public static class MyMcpComponents
{
    // --- Tools ---
    [McpPluginTool("calculate-sum", "Adds two numbers")]
    [Description("Adds two numbers")]
    public static int Add(int a, int b) => a + b;

    // --- Prompts ---
    [McpPluginPrompt("explain-code", "Explains a piece of code")]
    public static string ExplainCode(string code) => $"The following code: {code} does X, Y, and Z.";

    // --- Resources ---
    [McpPluginResource("system-logs", "Returns the latest system logs", "logs://system")]
    public static string GetLogs() => "Log entry 1: System started...";
}

Connecting to the Server:

using com.IvanMurzak.McpPlugin;
using com.IvanMurzak.ReflectorNet;

// 1. Initialize Reflector (The core engine)
var reflector = new Reflector();

// 2. Configure and build the plugin
var version = new com.IvanMurzak.McpPlugin.Common.Version
{
    Api = "1.0.0",
    Plugin = "1.0.0"
};
var plugin = new McpPluginBuilder(version)
    .WithConfig(config => {
        config.Host = "http://localhost:11111"; // Match your server port
    })
    // Option A: Scan assemblies for [McpPluginTool], [McpPluginPrompt], [McpPluginResource]
    .WithToolsFromAssembly(typeof(MyMcpComponents).Assembly)
    .WithPromptsFromAssembly(typeof(MyMcpComponents).Assembly)
    .WithResourcesFromAssembly(typeof(MyMcpComponents).Assembly)
    .Build(reflector);

// 3. Connect to the MCP server
await plugin.Connect();

Server (`McpPlugin.Server`)

Command-line arguments take priority over environment variables.

Analytics Webhooks

McpPlugin.Server can emit fire-and-forget HTTP POST notifications to external endpoints for observability and analytics. Each event category has an independent URL, so you can route tool, prompt, resource, and connection events to different systems.

Example — enable tool and connection analytics:

dotnet run \
  client-transport=stdio \
  webhook-tool-url=https://analytics.example.com/hooks/tools \
  webhook-connection-url=https://analytics.example.com/hooks/connections \
  webhook-token=my-secret-token

Event payload structure (all events follow this envelope):

{
  "schemaVersion": "1.0",
  "eventType": "tool.call.completed",
  "timestamp": "2026-03-01T12:34:56.789Z",
  "data": {
    "toolName": "add",
    "requestSizeBytes": 42,
    "responseSizeBytes": 18,
    "status": "success",
    "durationMs": 150
  }
}

Supported event types:

Notes:

• Webhooks are fire-and-forget — delivery failures are logged but never block MCP responses.
• If no webhook URLs are configured, the entire subsystem is inactive with zero overhead.
• Use HTTPS endpoints in production to protect the security token in transit.

Authorization Webhooks

McpPlugin.Server can be configured with a synchronous authorization webhook that gates connections from both MCP clients (AI agents via HTTP) and McpPlugin clients (.NET apps via SignalR). Unlike the fire-and-forget analytics webhooks above, authorization webhooks block the connection until your endpoint responds.

Example — enable connection authorization with fail-closed behavior:

dotnet run \
  client-transport=stdio \
  webhook-authorization-url=https://auth.example.com/authorize \
  webhook-token=my-secret-token \
  webhook-authorization-fail-open=false

Request format (POST from server to your webhook):

For AI agent connections (authorization.ai-agent):

{
  "schemaVersion": "1.0",
  "eventType": "authorization.ai-agent",
  "timestamp": "2025-03-04T22:45:30.1234567Z",
  "connectionId": "trace-id-or-connection-id",
  "clientType": "ai-agent",
  "bearerToken": "<token-from-client>",
  "remoteIpAddress": "192.168.1.100",
  "userAgent": "claude-ai/1.0",
  "requestPath": "/mcp",
  "clientName": null,
  "clientVersion": null,
  "hmacSignature": "sha256=abc123..."
}

For plugin connections (authorization.plugin):

{
  "schemaVersion": "1.0",
  "eventType": "authorization.plugin",
  "timestamp": "2025-03-04T22:45:30.1234567Z",
  "connectionId": "trace-id-or-connection-id",
  "clientType": "plugin",
  "bearerToken": "<token-from-plugin>",
  "remoteIpAddress": null,
  "userAgent": null,
  "requestPath": null,
  "clientName": "my-unity-plugin",
  "clientVersion": "1.2.0",
  "hmacSignature": "sha256=def456..."
}

Note: The hmacSignature field is only present when webhook-token is configured. It contains an HMAC-SHA256 signature of the request body (before the signature field is added), computed using the webhook token as the secret key.

Expected response format (from your webhook to server):

{ "allowed": true }

or

{ "allowed": false, "reason": "IP not in allowlist" }

Behavior:

• 2xx response with allowed: true → Connection proceeds
• 2xx response with allowed: false → Connection denied (reason logged as warning)
• Non-2xx response, timeout, or parse error → Connection denied (unless fail-open=true)

Security:

• The server sends the configured security token in the header named by webhook-header (default: X-Webhook-Token)
• Your webhook must validate this token to prevent unauthorized authorization requests
• Use HTTPS endpoints in production

Notes:

• Authorization webhooks are synchronous — the server waits (default timeout 10 seconds) for your response
• Keep webhook response times under 1 second for best performance
• Authorization webhooks operate independently from the analytics webhooks above
• If webhook-authorization-url is not configured, authorization is disabled (all connections allowed)

Plugin (`McpPlugin`)

Command-line arguments and environment variables are parsed automatically via ConnectionConfig.BuildFromArgsOrEnv(). They can also be overridden programmatically via McpPluginBuilder.WithConfig(...).

Programmatic-only properties (set via WithConfig(...)):