MCP Client Setup

Configure Claude Desktop, Cursor, or Codex to launch the PocketAgent MCP server.

Base configuration

After installing pokt-agent-mcp, add this block to your MCP client config:

{
  "mcpServers": {
    "pocketagent": {
      "command": "pocketagent-mcp",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ENCRYPTION_KEY": "your-32-byte-key",
        "JWT_SECRET": "your-jwt-secret",
        "DATABASE_PATH": "/absolute/path/to/pocketagent.db"
      }
    }
  }
}

DATABASE_PATH

When installed via pip, use an absolute path for DATABASE_PATH so agent rows resolve regardless of the MCP client's working directory.

Client-specific paths

Client	Config file
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\\Claude\\claude_desktop_config.json
Cursor	.cursor/mcp.json (project) or global MCP settings
Codex / other	Equivalent mcpServers JSON in client settings

Source install alternative

If running from the repository without pip:

{
  "mcpServers": {
    "pocketagent": {
      "command": "python",
      "args": ["-m", "pocketagent.mcp_server.server"],
      "cwd": "/path/to/PocketAgent/backend",
      "env": { ... }
    }
  }
}

Write tools and agent context

Read tools work without an agent. Transact tools (sends, contract writes, token transfers) require an agent_id and valid access token in the tool arguments. Create agents via the REST API or web UI first — see Create an Agent.

Module invocation (debugging)

python -m pocketagent.mcp_server.server

Blocks on stdio until a client connects. Use only for debugging transport issues.