MCP Servers: Model Context Protocol Setup

PocketPaw has first-class support for the Model Context Protocol (MCP). Connect any MCP server to extend your agent’s capabilities — including remote servers that use OAuth authentication.

What is MCP?

MCP is an open protocol that allows AI agents to connect to external tools and data sources. MCP servers provide tools that the agent can call, similar to built-in tools but running as separate processes.

Configuration

MCP servers are configured in ~/.pocketpaw/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "transport": "stdio"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "transport": "http",
      "oauth": true
    },
    "remote-api": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http"
    }
  }
}

Transport Types

stdio

The most common transport for local servers. PocketPaw spawns the MCP server as a subprocess and communicates via stdin/stdout:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
  "transport": "stdio"
}

http (auto-detect)

For remote MCP servers. PocketPaw tries Streamable HTTP first, then falls back to SSE automatically:

{
  "url": "https://example.com/mcp",
  "transport": "http"
}

This is the recommended transport for remote servers when you’re unsure which protocol they support.

streamable-http

Explicitly use the Streamable HTTP transport (modern MCP servers):

{
  "url": "https://example.com/mcp",
  "transport": "streamable-http"
}

sse

Explicitly use the SSE (Server-Sent Events) transport (older MCP servers):

{
  "url": "https://example.com/mcp/sse",
  "transport": "sse"
}

OAuth Authentication

Remote MCP servers (like GitHub, Notion, Linear) can use OAuth 2.1 for authentication. When a server requires OAuth:

1. Set "oauth": true in the server config (presets do this automatically)
2. On first connection, PocketPaw opens a browser popup for authentication
3. After authorization, tokens are stored in ~/.pocketpaw/mcp_oauth/{server_name}.json
4. Tokens are refreshed automatically on subsequent connections

How It Works

PocketPaw implements the full OAuth 2.1 flow:

• Metadata discovery — automatically finds the server’s OAuth endpoints
• PKCE — uses Proof Key for Code Exchange for security
• Dynamic client registration — registers as an OAuth client automatically
• CIMD fallback — if a server supports Client ID Metadata Documents, PocketPaw can use a pre-configured client URL instead of dynamic registration
• Token persistence — tokens are saved to disk (chmod 0600) and reused across restarts

CIMD (Client ID Metadata Document)

The OAuth 2.1 specification for MCP supports two ways for a client to identify itself:

1. Dynamic client registration — the client registers itself automatically with the OAuth server on first use. This is the simplest approach but not all servers support it.
2. CIMD — the client publishes a JSON metadata document at a public URL, and uses that URL as its client_id. The OAuth server fetches the CIMD to verify the client’s identity and redirect URIs.

Why GitHub MCP Needs CIMD

GitHub’s MCP server (https://api.githubcopilot.com/mcp/) does not support dynamic client registration. When PocketPaw tries to register as an OAuth client, GitHub rejects the request with a “Registration failed” error.

The solution is CIMD: you host a small JSON file at a publicly accessible URL, and PocketPaw uses that URL as its client_id instead of attempting dynamic registration. GitHub then fetches the CIMD to validate the redirect URIs before initiating the OAuth flow.

Setting Up CIMD

1. Host a CIMD JSON file at a public URL. The file should look like:

{
  "client_name": "PocketPaw",
  "redirect_uris": [
    "http://localhost:8888/api/mcp/oauth/callback",
    "http://127.0.0.1:8888/api/mcp/oauth/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "client_uri": "https://github.com/pocketpaw/pocketpaw",
  "software_id": "pocketpaw",
  "software_version": "0.4.1"
}

2. Set the URL in PocketPaw’s config:

export POCKETPAW_MCP_CLIENT_METADATA_URL="https://pocketpaw.xyz/mcp-client.json"

Or set it in ~/.pocketpaw/config.json:

{
  "mcp_client_metadata_url": "https://pocketpaw.xyz/mcp-client.json"
}

3. The redirect_uris in the CIMD must match your PocketPaw dashboard URL. If you run on a different port, update the CIMD accordingly.

Preset Catalog

PocketPaw includes 55+ pre-configured server templates that can be installed from the dashboard with a single click. Presets cover:

• Developer tools — GitHub, GitLab, Linear, Sentry
• Productivity — Notion, Slack, Google Drive, Obsidian
• Data & Search — PostgreSQL, Brave Search, Exa
• DevOps — Kubernetes, Docker, Cloudflare
• And more — Figma, Stripe, Spotify, Todoist

Presets that use OAuth are marked with an oauth flag and handle authentication automatically.

Backend Integration

Claude Agent SDK

The Claude Agent SDK has native MCP support. PocketPaw translates mcp.json configurations into the SDK’s expected format and passes them during initialization.

Google ADK

The Google ADK backend has native MCP support via McpToolset, supporting stdio, SSE, and HTTP transports.

Codex CLI

The Codex CLI backend forwards MCP server configurations to the Codex CLI process.

Dashboard Management

The web dashboard provides a visual interface for managing MCP servers:

1. Open the MCP modal from the sidebar
2. Browse the preset catalog or add custom servers
3. For OAuth servers, a browser popup handles authentication
4. Toggle individual servers on/off
5. View discovered tools from each server

REST API

Tool Policy

MCP tools are subject to the tool policy system:

# Allow all MCP tools
export POCKETPAW_TOOLS_ALLOW="group:mcp"

# Allow specific server's tools
export POCKETPAW_TOOLS_ALLOW="mcp:filesystem:*"

# Deny a specific tool
export POCKETPAW_TOOLS_DENY="mcp:github:delete_repo"

Error Handling

PocketPaw provides actionable error messages for MCP server failures:

• ExceptionGroup unwrapping — the MCP library wraps errors in anyio cancel-scope exceptions; PocketPaw walks the exception tree to surface the root cause
• OAuth registration failures — if dynamic client registration fails, the error message suggests configuring mcp_client_metadata_url or using an API token instead
• Timeout handling — clear messages distinguish connection timeouts from OAuth flow timeouts

Related