Connect external tools via MCP

Not every tool has to live in your project. A Model Context Protocol (MCP) server exposes a set of tools over a standard protocol, and agentc can connect to one and register every tool it offers. Unlike tools you write, MCP tools are not embedded at compile time; the manifest describes how to reach the server, and the server must be available when the agent runs. When the agent starts, it connects, queries the server for its tools, and registers each one automatically. For the full field reference, see the tool reference.

Connect to a local server over stdio

The stdio transport spawns the server as a child process and talks to it over standard input and output. This is the usual way to run a local MCP server:

tool "time" {
  kind      = "mcp"
  transport = "stdio"
  command   = "uvx"
  args      = ["mcp-server-time"]
}

Both command and individual args entries accept runtime(), so you can configure the server from the environment:

tool "filesystem" {
  kind      = "mcp"
  transport = "stdio"
  command   = "npx"
  args      = ["-y", "@modelcontextprotocol/server-filesystem", runtime("FS_MCP_WORKSPACE", "/workspace")]
}

Connect to a remote server over HTTP

The HTTP transport connects to a remote MCP server. Use secret(runtime(...)) for the auth token so it stays out of logs and build output:

tool "remote_tools" {
  kind       = "mcp"
  transport  = "http"
  url        = runtime("MCP_SERVER_URL", "https://tools.example.com")
  auth_token = secret(runtime("MCP_AUTH_TOKEN"))
  headers    = {
    "X-Client-ID" = runtime("CLIENT_ID")
  }
}

Apply capabilities to a server's tools

A capabilities list on the tool block applies its tags to every tool discovered from that server, so you can gate a whole server behind a capability the agent must hold:

tool "my_service" {
  kind         = "mcp"
  transport    = "http"
  url          = runtime("SERVICE_URL")
  capabilities = ["my_service"]
}

See Control tool access with capabilities for how capabilities gate access.

Where to go next

• Tools and capabilities: how MCP tools sit alongside the other kinds.
• Control tool access with capabilities: restrict what a connected server exposes.
• tool reference: every stdio and HTTP field for MCP tools.