MCP Support

A3S Code supports the Model Context Protocol (MCP) for integrating external tool servers. MCP tools are automatically registered in the ToolExecutor when a server connects.

Transports

Configuration

stdio Transport

For local MCP servers that run as child processes:

mcp_servers {
  name      = "filesystem"
  transport = "stdio"
  command   = "npx"
  args      = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  enabled   = true
}

mcp_servers {
  name      = "github"
  transport = "stdio"
  command   = "npx"
  args      = ["-y", "@modelcontextprotocol/server-github"]
  enabled   = true
  env = {
    GITHUB_TOKEN = "ghp_..."
  }
}

HTTP+SSE Transport

For remote MCP servers using the legacy SSE transport:

mcp_servers {
  name      = "remote-tools"
  transport = "http"
  url       = "https://mcp.example.com/sse"
  enabled   = true
  headers = {
    Authorization = "Bearer token-..."
  }
}

Requests are sent via HTTP POST to the base URL; responses stream back via Server-Sent Events from a /sse endpoint.

Streamable HTTP Transport

For remote MCP servers implementing the MCP 2025-03-26 spec:

mcp_servers {
  name      = "remote-tools"
  transport = "streamable-http"
  url       = "https://mcp.example.com/mcp"
  enabled   = true
  headers = {
    Authorization = "Bearer token-..."
  }
}

All communication goes through a single endpoint. The server may respond with plain JSON or an SSE stream. Sessions are tracked via the Mcp-Session-Id header and terminated with a DELETE request on close.

Tool Naming

MCP tools are namespaced with the server name to avoid collisions:

mcp__<server_name>__<tool_name>

For example, a tool read_file from server filesystem becomes mcp__filesystem__read_file.

Permission Integration

MCP tools respect the same permission system as built-in tools. Use the namespaced prefix in permission rules:

mcp__filesystem  → matches all tools from the filesystem server
mcp__github      → matches all tools from the github server

Shadowing Prevention

MCP tools cannot shadow built-in tool names. If an MCP server exposes a tool named Bash, Read, Write, or any other built-in name, the tool registration is rejected. This prevents malicious MCP servers from intercepting sensitive operations.

Execution Timeout

MCP tool executions have a configurable timeout (default: 60 seconds). If a tool doesn't respond within the timeout, the execution is cancelled and an error is returned. This prevents hanging MCP servers from blocking the agent.

API Reference

HCL configuration

mcp_servers {
  name    = "filesystem"
  command = "npx"
  args    = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
}

mcp_servers {
  name = "github"
  command = "npx"
  args    = ["-y", "@modelcontextprotocol/server-github"]
  env     = { GITHUB_TOKEN = env("GITHUB_TOKEN") }
}

mcp_servers {
  name      = "remote"
  transport = "streamable-http"
  url       = "https://mcp.example.com/mcp"
  headers   = { Authorization = "Bearer token" }
}

MCP server config fields

Tool naming

MCP tools are namespaced as mcp__{server}__{tool}. Use this prefix in permission rules:

Dynamic MCP Server Registration

Use add_mcp_server() to connect an MCP server to a live session at runtime — without restarting the agent or reloading config. The server is launched, its tools are discovered, and they are immediately available for the next LLM turn.

import { Agent } from '@a3s-lab/code'; // v0.9.5

const agent = await Agent.create('agent.hcl');
const session = agent.session('.');

// stdio server
const toolCount = await session.addMcpServer(
  'filesystem',
  'stdio',
  'npx',
  ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
);
console.log(`Registered ${toolCount} tools`);

// Streamable HTTP server
await session.addMcpServer(
  'remote',
  'streamable-http',
  undefined,
  undefined,
  'https://mcp.example.com/mcp',
  { Authorization: `Bearer ${process.env.API_TOKEN}` },
);

const result = await session.send('List files in /tmp');

from a3s_code import Agent  # v0.9.5

agent = Agent.create("agent.hcl")
session = agent.session(".")

# stdio server
tool_count = session.add_mcp_server(
    "filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
)
print(f"Registered {tool_count} tools")

# Streamable HTTP server
session.add_mcp_server(
    "remote",
    transport="streamable-http",
    url="https://mcp.example.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['API_TOKEN']}"},
)

result = session.send("List files in /tmp")

add_mcp_server parameters

Returns the number of tools registered from the server. Throws if the server fails to start or the initial list_tools call fails.