MCP Servers

Amodal connects to Model Context Protocol servers and exposes their tools to agents.

Configuration

Define an MCP connection in amodal/connections/<name>/spec.json:

{
  "protocol": "mcp",
  "transport": "http",
  "url": "https://tools.example.com/mcp",
  "auth": {
    "type": "bearer",
    "token": "env:TOOLS_TOKEN"
  }
}

Set TOOLS_TOKEN to the token alone; bearer authentication adds the Bearer prefix. This is the format generated by Studio's static bearer option and amodal connections add tools --mcp <url> --auth bearer.

An explicit header such as "headers": {"Authorization": "env:TOOLS_AUTHORIZATION"} also works. In that form, set TOOLS_AUTHORIZATION to the complete header value, including Bearer if required. Header references replace the whole value without adding a prefix.

For OAuth over http or sse, declare "auth": {"type": "oauth2"} and follow OAuth connections. Studio and CLI MCP creation default to OAuth, and Studio ships presets for common remote servers.

MCP connections need no baseUrl, format, or policy.json. The model receives the server's own tool descriptions and schemas. Connection policies, field restrictions, and surface.md do not apply to MCP calls.

Servers can also be defined under mcp.servers in amodal.json with the same command, args, env, url, and headers fields; transport is required there. A connection with the same name takes precedence.

Transports

Transport	Fields	Requirement
`stdio`	`command`, `args`, `env`	The default when `transport` is omitted. The runtime environment must contain the executable and its dependencies.
`sse`	`url`, optional `headers`	An accessible MCP server using SSE transport.
`http`	`url`, optional `headers`	An accessible MCP server using Streamable HTTP.

Credential-like env and headers entries, such as names ending in token, key, secret, or password, must be env:NAME references. A scope:KEY reference passes validation but is not resolved for MCP servers, so the server receives the literal string:

{
  "protocol": "mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["/opt/tools/server.mjs"],
  "env": { "SERVICE_TOKEN": "env:SERVICE_TOKEN" }
}

Tool Discovery

Tools are named <server>__<tool>, using the connection directory name or the mcp.servers key:

internal-tools__lookup_ticket
internal-tools__add_comment

A named root agent must declare the server in its mcp list:

{
  "mcp": ["internal-tools"]
}

Use mcp for MCP servers, including servers defined as connections. Use connections for REST connections. Unscoped chat exposes all discovered MCP tools. If agents/default/ exists, a chat request that omits agent uses that agent's mcp declarations. A delegated specialist declares individual inherited MCP tool names in tools.

Tools are discovered when the server connects. A server that fails to connect is logged and skipped, and the agent starts without its tools. Test connection in Studio lists a connected server's tools.