MCP Servers

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

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.

AgentConfiguration (or a blueprint agent entry)

{
    "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. Inspect the warning and required capabilities before accepting work.

Code-Driven (Manual Control)

The following method fragment assumes AIAgent and AgentSession fields named _agent and _session. 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 = "LocalTools",
        Command = "my-mcp-server",
        Arguments = [] // Arguments for your installed server
    });

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

    // Pass to CreateChatClientAgent as usual
    var created = await CreateChatClientAgent(config.Models!, "main", tools);
    _agent = created.Agent;
    _session = created.Session;
}

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:

Property	Type	Default	Description
`Name`	`string?`	`null`	Friendly name for logging and diagnostics
`TransportType`	`"Stdio"` or `"Http"`	`"Stdio"`	Transport protocol
`Command`	`string?`	`null`	Stdio only. Executable to run (e.g. `"npx"`, `"uvx"`, `"docker"`)
`Arguments`	`string[]`	`[]`	Stdio only. Command-line arguments
`Env`	`object`	`{}`	Stdio only. Environment variables passed to the process
`Url`	`string?`	`null`	Http only. Server endpoint URL
`Headers`	`object`	`{}`	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

Scenario	Behavior
Config-driven MCP fails to connect	Warning logged, agent starts without that server's tools
Code-driven MCP fails to connect	Exception propagates to caller
MCP server process dies after connection	Tool invocations can fail; handle and surface failures rather than assuming model recovery.

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.

Authenticated MCP connections

Set McpServerConfig.Connection and Resource for HTTP MCP token acquisition through the broker. Omit static Authorization headers. Reconfigure the MCP session after replacing or reauthorizing a connection. Read the integration guide.