MCP Servers

Amodal connects to Model Context Protocol servers and exposes their discovered 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, declare "auth": {"type": "oauth2"} and follow OAuth connections. Studio and CLI MCP creation default to OAuth.

Amodal's Add connection picker ships ready-made entries for common remote MCP servers, including Linear, Jira and Confluence, Notion, GitLab, Sentry, Stripe, and Datadog. Picking one writes this definition and signs in without registering an application. See Add a connection in Amodal.

MCP connections do not require baseUrl, format, or policy.json. The model receives the server's tool descriptions and schemas. REST surface.md endpoint listings and connection policies do not control MCP calls.

You can also define servers under mcp.servers in amodal.json.

Transports

Transport	Fields	Requirement
`stdio`	`command`, `args`, `env`	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.

For example, a server supplied in your runtime environment can run over stdio:

{
  "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.

Native OpenAPI connections use the same double-underscore separator and add a discovery tool. MCP discovery happens when the server connects.

Deployment

Deploy the agent with its server configuration and credentials. Inspect the runtime's discovered tools and startup logs to confirm the server connected.

A server that fails to connect is logged and skipped; the agent and other servers can still start. The failed server's tools are unavailable. Connections are closed when the runtime shuts down.