MCP Servers

Amodal supports the Model Context Protocol for connecting external tool servers. MCP tools appear alongside your custom tools and built-in tools — the agent uses them transparently.

Configuration

The recommended way to define an MCP server is as a connection with "protocol": "mcp" in its spec.json:

amodal/connections/github/
└── spec.json

{
  "protocol": "mcp",
  "transport": "stdio",
  "command": "uvx",
  "args": ["mcp-server-github"],
  "env": { "GITHUB_TOKEN": "env:GITHUB_TOKEN" }
}

This gives you all the benefits of the connections directory — surface.md documentation, rules.md business rules, and a unified view in Amodal. MCP connections do not require policy.json.

Transports

Transport	Config	Use Case
`stdio`	`command`, `args`, `env`	Local tools via child process
`sse`	`url`, `headers`	Server-Sent Events over HTTP
`http`	`url`, `trust`, `headers`	Streamable HTTP transport

The headers field is optional. Use it for authenticated MCP servers that require a Bearer token or other HTTP headers.

Tool Discovery

MCP tools are automatically discovered when servers connect. Tools are namespaced with the server name (or connection directory name) to avoid collisions:

github__create_issue
github__list_repos
filesystem__read_file

The separator is __ (double underscore).

Deployment

# MCP servers start with the deployed agent runtime
Deploy the agent from Amodal
 
# The agent sees MCP tools alongside custom and built-in tools
Use Amodal inspect views to review discovered tools including MCP

Behavior

Non-fatal startup — if an MCP server fails to connect, other servers and the agent still work
Auto-discovery — tools are discovered after connection, no manual registration needed
Graceful shutdown — servers are cleaned up when the runtime stops
Environment variables — use env:VAR_NAME pattern for credentials

Example: GitHub MCP (Connection Directory)

// amodal/connections/github/spec.json
{
  "protocol": "mcp",
  "transport": "stdio",
  "command": "uvx",
  "args": ["mcp-server-github"],
  "env": {
    "GITHUB_TOKEN": "env:GITHUB_TOKEN"
  }
}

This gives the agent access to GitHub tools (create issues, list PRs, read files, etc.) via the GitHub MCP server.

Example: Authenticated HTTP MCP

// amodal/connections/internal-tools/spec.json
{
  "protocol": "mcp",
  "transport": "http",
  "url": "https://tools.internal.acme.com/mcp",
  "headers": {
    "Authorization": "env:INTERNAL_TOOLS_TOKEN"
  },
  "trust": true
}

Use headers to pass Bearer tokens or API keys to authenticated MCP servers.