MCP Servers

The mcp-servers block defines external tool servers that agents can connect to via the Model Context Protocol (MCP). This lets agents use databases, APIs, browsers, and any other MCP-compatible service.

Basic Syntax

mcp-servers {
  postgres {
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env: {
      DATABASE_URL: "${DATABASE_URL}"
    }
  }
}

Field Reference

Field	Type	Required	Description
`type`	identifier	Yes	Transport type: `stdio`, `http`, or `sse`
`command`	string	Conditional	Command to start the server (required for `stdio`)
`args`	list	No	Arguments passed to the command
`url`	string	Conditional	Server URL (required for `http` and `sse`)
`env`	block	No	Environment variables passed to the server

Transport Types

stdio

The server runs as a local process. Communication happens over stdin/stdout:

mcp-servers {
  filesystem {
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  }
}

http

The server runs remotely and communicates over HTTP:

mcp-servers {
  custom-api {
    type: http
    url: "https://mcp.example.com/api"
  }
}

sse

The server uses Server-Sent Events for streaming communication:

mcp-servers {
  realtime {
    type: sse
    url: "https://mcp.example.com/sse"
  }
}

Environment Variables

Pass secrets and configuration to MCP servers using env. Reference topology-level environment variables with ${VAR_NAME}:

mcp-servers {
  github {
    type: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env: {
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    }
  }
}

Agent References

Agents connect to MCP servers by listing them in their mcp-servers field. Use the mcp.server.* wildcard in tools to grant access to all tools from a server:

agent data-analyst {
  model: sonnet
  mcp-servers: [postgres]
  tools: [mcp.postgres.*]
}

You can also reference specific tools from an MCP server:

agent reader {
  model: sonnet
  mcp-servers: [postgres]
  tools: [mcp.postgres.query, mcp.postgres.list-tables]
}

Full Example

topology data-pipeline : [pipeline] {
  mcp-servers {
    postgres {
      type: stdio
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-postgres"]
      env: {
        DATABASE_URL: "${DATABASE_URL}"
      }
    }

    browser {
      type: stdio
      command: "npx"
      args: ["-y", "@playwright/mcp"]
    }
  }

  agent scraper {
    model: sonnet
    mcp-servers: [browser]
    tools: [mcp.browser.*]
  }

  agent analyst {
    model: opus
    mcp-servers: [postgres]
    tools: [mcp.postgres.*]
  }

  flow {
    scraper -> analyst
  }
}

Tips

Use stdio for local MCP servers and http/sse for remote ones.
Always use ${VAR_NAME} for secrets — never hardcode credentials in .at files.
The mcp.server.* wildcard grants all tools. Use specific tool names for tighter access control.
An agent must list a server in its mcp-servers field before it can use that server's tools.

MCP Servers

On this page