albedo docs

MCP servers

Connect Model Context Protocol (mcp) servers over stdio or HTTP so agents can use the tools they offer, such as an issue tracker, a database, or a design file.

On this page: Configure servers, Filter tools and tune timeouts, and Use a server's tools.

Configured servers are provided by the mcp extension (enabled via /mcp or /extensions), while editor-supplied servers during albedo acp use editor-mcp (enabled by default).

Configure servers

Open /mcp in the terminal or web client to add, edit, enable, disable, or sign in to servers, or configure them under the "mcp" section in extensions.json. Each server name is 1–64 characters of letters, digits, _, and - starting with a letter or digit.

Stdio servers

A stdio server launches a local subprocess:

{
  "mcp": {
    "retryMs": 30000,
    "servers": {
      "github": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": { "env": "GITHUB_TOKEN" }
        },
        "startupTimeoutMs": 20000,
        "callTimeoutMs": 60000
      }
    }
  }
}

Stdio processes start with a stripped environment (HOME, PATH, TMPDIR, TEMP, TMP, SystemRoot, WINDIR) plus the variables declared in env, so list any additional environment variables the server needs explicitly.

HTTP servers and OAuth

An HTTP server connects to an http or https endpoint (without embedded user info or URL fragments) and supports static headers, bearer token env vars, or OAuth sign-in through /mcp:

{
  "mcp": {
    "servers": {
      "linear": {
        "type": "http",
        "url": "https://mcp.linear.app/mcp",
        "headers": {
          "X-Workspace": "eng"
        },
        "bearerTokenEnvVar": "LINEAR_TOKEN"
      }
    }
  }
}

OAuth credentials are stored in creds.json (mode 0600). Environment references in env, headers, and bearerTokenEnvVar are resolved when the transport connects rather than when settings are saved.

Filter tools and tune timeouts

Use a server's tools

Once a server is connected, talk about the work, not the tool. The agent searches every connected server for a fitting tool, so you rarely need to name one:

people keep mentioning login timeouts. can you see what's in linear about it and catch me up?

that bug we just found deserves an issue. can you file it on github with the failing test? write it up however you think is clearest.

i just connected the notion server. have a look around and tell me what you can do with it?

When you run an editor through albedo acp, the MCP servers the editor advertises are available alongside the ones you configured.

What a server says about itself and what its tools return are treated as untrusted external data, never as instructions from you. See the MCP implementation reference for catalogue caching and timeout behavior.

Previous skills & instructions Next agents & worktrees