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

A3S Code supports two MCP 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 accessible over HTTP:

mcp_servers {
  name      = "remote-tools"
  transport = "sse"
  url       = "https://mcp.example.com/sse"
  enabled   = true
  env = {
    API_TOKEN = "token-..."
  }
}

The HTTP+SSE transport connects to a remote server endpoint. Requests are sent via HTTP POST, and responses stream back via Server-Sent Events. This is useful for shared MCP servers in team environments or cloud-hosted tool providers.

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 server config fields

McpTransport trait (Rust)

Tool naming

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