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:

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 the admin UI. MCP connections do not require access.json.

Legacy: amodal.json

MCP servers can also be defined in the mcp.servers block of amodal.json. This still works but the connection-directory approach above is preferred:

{
  "mcp": {
    "servers": {
      "github": {
        "transport": "stdio",
        "command": "uvx",
        "args": ["mcp-server-github"],
        "env": { "GITHUB_TOKEN": "env:GITHUB_TOKEN" }
      },
      "filesystem": {
        "transport": "sse",
        "url": "http://localhost:8001"
      },
      "docs": {
        "transport": "http",
        "url": "https://docs.example.com/api/mcp",
        "trust": true
      }
    }
  }
}

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).

CLI

# MCP servers start automatically with amodal dev
amodal dev
 
# The agent sees MCP tools alongside custom and built-in tools
amodal inspect   # shows all 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)

// 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

// 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.