MCP Integration

Aleph's MCP host manages external server connections; native filesystem, shell, and other built-in capabilities do not belong to McpClient. Servers connect over stdio, HTTP, or SSE, and the initialize handshake negotiates the protocol version and records server capabilities.

Connections and Transports

ExternalServerConfig stores the server name, command, arguments, environment, working directory, runtime requirement, and timeout. The connection layer supports:

• StdioTransport for local subprocesses;
• HttpTransport for remote HTTP POST;
• SseTransport for remote HTTP + SSE with server notifications.

After initialization, the connection drains paginated tools/list, normalizes the tool definition, and registers it under the <server>:<tool> namespace. Tool descriptions are untrusted input; schemas are normalized, and MCP annotations conservatively affect scheduling and confirmation without replacing Aleph's security policy.

Capability Gates

The MCP initialize result's ServerCapabilities distinguishes tools, resources, and prompts. The connection layer calls resources/list, resources/templates/list, or prompts/list only when the server declares the corresponding capability; results are cached and paginated.

The MCP tool bridge dynamically registers capability tools based on the capabilities of healthy connected servers:

Resource reading and resource discovery share one gate, so a template-only server still receives read and discovery tools. Prompt reading and prompt discovery are likewise paired. Without the corresponding capability, the tools are removed from the registry instead of being shown to the model as guaranteed failures.

On-Demand Discovery

Resources and prompts are not projected into a prebuilt prompt index. The current path is mcp_list_resources, mcp_list_resource_templates, and mcp_list_prompts: the model discovers first, then passes the exact opaque ID returned to the read tool. A cat-guard read-steer routes file reads to native MCP, skill, or plugin paths.

MCP tools can also be placed in the progressive-disclosure deferred tier by [tools] defer_mcp_tools and retrieved through tool_search; this is separate from resource/prompt capability gating.

Resource, Template, and Prompt Names

Resources and prompts returned by a server are namespaced. Discovery tools build IDs that must be copied verbatim; they must not be shortened or reconstructed. A cached resource is already <server>:<uri>, and discovery wraps it with another server prefix so the read tool strips the discovery layer and the client then strips the connection layer before sending the original URI to the server. Resource templates retain their raw RFC 6570 pattern; after filling it, the model reads it using the returned server-qualified form.

Server IDs may themselves contain colons. McpClient and mcp_read_resource/mcp_get_prompt use the same longest-prefix rule: candidates are tried from the rightmost colon, selecting the longest registered <server>: prefix, and exactly one layer is stripped. If both gh and gh:sub exist, gh:sub:file:///x routes to gh:sub rather than being misrouted to gh.

Configuration and Security

The MCP manager owns server start/stop, health, capability-change events, aggregation, and configuration reload. Remote connections use configured HTTP/SSE transports and the OAuth login tool; local servers check declared Node, Python, Bun, or other runtimes before launch. Per-server allow/deny filtering runs when tools/list enters the registry, so denied tools are neither registered nor advertised; Aleph's own permission, confirmation, and sandbox boundaries still apply at execution time.

The client advertises its wired sampling capability and honors the protocol version returned by the server. Resource and prompt list changes propagate through MCP manager events, allowing the tool bridge to reconcile the registry.

Code Location

• src/mcp/client.rs — external registry, resource/prompt lookup, and longest-prefix matching
• src/mcp/external/connection.rs — initialization, capability checks, pagination, and caches
• src/mcp/protocol.rs — MCP initialization and capability types
• src/mcp/tool_bridge.rs — capability-gated tool registration
• src/builtin_tools/mcp_resource.rs — resource, template, and read tools
• src/builtin_tools/mcp_prompt.rs — prompt discovery and read tools
• src/mcp/resources.rs, src/mcp/prompts.rs — manager interfaces
• src/tools/adapters/mcp_adapter.rs — MCP tool execution adapter

See Also

• Builtin Tools — native tool registry
• Tool Infrastructure — deferred tools and permission execution
• Extension System — plugin-owned MCP servers