MCP Servers

Connect to external tools via the Model Context Protocol.

otto supports MCP (Model Context Protocol) — the open standard for connecting AI agents to external tools and data sources. Add local or remote MCP servers to extend your agent with tools like GitHub, Linear, Notion, Helius, databases, and more.

Quick Start

From the Web UI

1. Open the MCP panel in the right sidebar (blocks icon)
2. Click + to add a server
3. Choose Local (stdio) or Remote (HTTP)
4. Fill in the details and click Add Server
5. Click ▶ to start — tools become available to the agent

From the CLI

# Add a local server
otto mcp add github --command npx --args -y @modelcontextprotocol/server-github

# Add a remote server
otto mcp add linear --transport http --url https://mcp.linear.app/mcp

# List / test / status
otto mcp list
otto mcp test github
otto mcp status

# Authenticate with an OAuth server
otto mcp auth linear

# Remove a server
otto mcp remove github

From Config

Add servers to .otto/config.json (project) or ~/.config/otto/config.json (global):

{
  "mcp": {
    "servers": [
      {
        "name": "github",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
      },
      {
        "name": "helius",
        "command": "npx",
        "args": ["-y", "helius-mcp@latest"],
        "env": { "HELIUS_API_KEY": "your-key-here" }
      },
      {
        "name": "linear",
        "transport": "http",
        "url": "https://mcp.linear.app/mcp"
      }
    ]
  }
}

Transports

Local Servers (stdio)

Local servers are spawned as child processes. The server communicates over stdin/stdout using JSON-RPC.

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}

Remote Servers (HTTP/SSE)

Remote servers connect over the network. Use http for modern servers, sse for legacy.

{
  "name": "linear",
  "transport": "http",
  "url": "https://mcp.linear.app/mcp"
}

For servers with API key auth, pass static headers:

{
  "name": "my-server",
  "transport": "http",
  "url": "https://mcp.example.com",
  "headers": {
    "Authorization": "Bearer sk-xxx"
  }
}

OAuth Authentication

Remote servers like Linear, Notion, and Sentry use OAuth. otto handles the full OAuth 2.0 + PKCE flow automatically.

How It Works

1. Start a remote server → server returns 401
2. otto detects auth is required → yellow lock icon in sidebar
3. Browser opens automatically with the OAuth authorization URL
4. You authorize → provider redirects to localhost:8090/callback
5. otto receives the code, exchanges for tokens, and reconnects
6. Server turns green — tools are now available

CLI Auth

# Start the OAuth flow
otto mcp auth linear

# Check auth status
otto mcp auth linear --status

# Revoke stored credentials
otto mcp auth linear --revoke

OAuth Config

For servers that need custom OAuth settings:

{
  "name": "linear",
  "transport": "http",
  "url": "https://mcp.linear.app/mcp",
  "oauth": {
    "clientId": "your-client-id",
    "callbackPort": 8090,
    "scopes": ["read", "write"]
  }
}

Tokens are stored in ~/.config/otto/oauth/ with 0600 permissions and refresh automatically.

How Tools Work

When an MCP server is started, otto:

1. Connects to the server (stdio/HTTP/SSE)
2. Calls tools/list to discover available tools
3. Converts each tool to an AI SDK-compatible format
4. Registers tools as servername__toolname

For example, starting the helius server exposes:

• helius__getBalance
• helius__searchAssets
• helius__getTransactionHistory

These tools are automatically available to all agents alongside built-in tools. MCP tools bypass the per-agent tool allowlist — any running server's tools are available to every agent.

Config Reference

Popular MCP Servers

Browse more at mcp.run and awesome-mcp-servers.

Troubleshooting

Server won't start

• Check the command exists: which npx
• Check env vars are set — use otto mcp test <name>
• For remote servers, check the URL is reachable

Tools not appearing

• Make sure the server is started (green dot in sidebar)
• MCP tools are loaded fresh each session
• Use otto mcp status to verify tools are indexed

OAuth flow not completing

• Ensure port 8090 is not in use
• Check your browser didn't block the popup
• Try otto mcp auth <name> from CLI for details
• Use otto mcp auth <name> --revoke and retry