Home / Docs / MCP Servers

MCP Servers

MCP Servers

FabrCore supports connecting MCP (Model Context Protocol) servers to agents, giving them access to external tools (GitHub, filesystem, databases, etc.) with zero agent code changes.

Config-Driven (Zero Code)

Add McpServers to your agent configuration JSON. No agent code changes needed — ResolveConfiguredToolsAsync() automatically connects MCP servers and includes their tools alongside plugin and standalone tools.

fabrcore.json 
{
    "Handle": "coding-agent",
    "AgentType": "CodingAgent",
    "Models": "OpenAIProd",
    "McpServers": [
        {
            "Name": "GitHub",
            "TransportType": "Stdio",
            "Command": "npx",
            "Arguments": ["-y", "@modelcontextprotocol/server-github"],
            "Env": { "GITHUB_TOKEN": "ghp_xxx" }
        }
    ]
}
Graceful Fallback

If an MCP server fails to connect in config-driven mode, a warning is logged and the agent continues with its other tools. No crash, no downtime.

Code-Driven (Manual Control)

For dynamic connections at runtime, call ConnectMcpServerAsync() directly in your agent proxy:

CodingAgentProxy.cs 
public override async Task OnInitialize()
{
    var mcpTools = await ConnectMcpServerAsync(new McpServerConfig
    {
        Name = "GitHub",
        Command = "npx",
        Arguments = ["-y", "@modelcontextprotocol/server-github"],
        Env = new() { ["GITHUB_TOKEN"] = Environment.GetEnvironmentVariable("GITHUB_TOKEN")! }
    });

    // Combine with other tools
    var tools = await ResolveConfiguredToolsAsync();
    tools.AddRange(mcpTools);

    // Pass to CreateChatClientAgent as usual
    _agent = await CreateChatClientAgent(config.Models!, config.Handle!, tools);
}
Exception Handling

In code-driven mode, exceptions propagate to your code — you decide how to handle failures.

McpServerConfig Properties

The McpServerConfig class defines how to connect to an MCP server:

PropertyTypeDefaultDescription
Namestring?nullFriendly name for logging and diagnostics
TransportType"Stdio" or "Http""Stdio"Transport protocol
Commandstring?nullStdio only. Executable to run (e.g. "npx", "uvx", "docker")
Argumentsstring[][]Stdio only. Command-line arguments
Envobject{}Stdio only. Environment variables passed to the process
Urlstring?nullHttp only. Server endpoint URL
Headersobject{}Http only. Custom HTTP headers (auth tokens, etc.)

Transport Types

Stdio

Launches a local process and communicates over stdin/stdout. Ideal for CLI-based MCP servers:

Stdio — GitHub MCP Server 
{
    "Name": "GitHub",
    "TransportType": "Stdio",
    "Command": "npx",
    "Arguments": ["-y", "@modelcontextprotocol/server-github"],
    "Env": { "GITHUB_TOKEN": "ghp_xxx" }
}

Http

Connects to a remote MCP server over HTTP. Use for shared or hosted MCP services:

Http — Remote MCP Server 
{
    "Name": "MyRemoteTools",
    "TransportType": "Http",
    "Url": "https://mcp.example.com/sse",
    "Headers": { "Authorization": "Bearer sk-xxx" }
}

Lifecycle

MCP connections are fully managed by FabrCore:

  • MCP clients are automatically disposed when the agent grain deactivates — no cleanup code needed.
  • MCP tools are standard AITool instances, fully compatible with CreateChatClientAgent() and ChatOptions.Tools.

Error Behavior

ScenarioBehavior
Config-driven MCP fails to connectWarning logged, agent starts without that server's tools
Code-driven MCP fails to connectException propagates to caller
MCP server process dies after connectionTool invocations throw; the LLM handles gracefully

Health Diagnostics

When MCP servers are connected, the agent health endpoint includes McpServerConnections in its custom metrics. Query via the existing health API:

Health Check 
GET /api/agents/{handle}/health?detailLevel=Full
Compatibility

MCP tools are standard AITool instances. They work with all existing FabrCore features — plugins, AIContextProvider, telemetry, and health monitoring.

Documentation