Remote MCP Server Architecture & Protocols

The Pocket Kit Remote MCP Server connects AI developer agents to your live PocketBase databases over the standard Model Context Protocol (MCP). It is a hybrid multi-transport gateway supporting real-time streaming, stateless HTTP RPC, and enterprise OAuth authentication.

---

1. Supported Transport Protocols

Pocket Kit supports three primary transport methods to accommodate every type of AI agent:

Transport Mode	Endpoint URL	Ideal For	Authentication
Remote SSE	https://mcp.pocket-kit.naftalmatoya.tech/sse	Claude.ai, Cursor, Windsurf, Claude Desktop	Bearer Token or OAuth 2.0 PKCE
Direct JSON-RPC	https://mcp.pocket-kit.naftalmatoya.tech/mcp/call	Python / TypeScript Custom Agents, LangChain	Authorization: Bearer fuko_mcp_...
Local Stdio Bridge	npx @pocket-kit/mcp --stdio	Local IDE terminals & air-gapped workstations	API Token via environment variable

---

2. Authentication & Authorization Flows

flowchart TD
    subgraph Clients["AI Clients"]
        ClaudeWeb["Claude.ai / Web Agent"]
        ClaudeCLI["Claude Code / Terminal CLI"]
        Cursor["Cursor IDE / Windsurf"]
    end

    subgraph AuthGateways["Pocket Kit Auth Gateways"]
        OAuthPKCE["1. OAuth 2.0 PKCE Consent Screen\n(/oauth/authorize)"]
        DeviceCode["2. RFC 8628 Device Code Flow\n(/oauth/device/code)"]
        BearerToken["3. Personal MCP Token\n(Bearer fuko_mcp_...)"]
    end

    subgraph CoreEngine["Pocket Kit MCP Engine (18 Tools)"]
        Cedar["AWS Cedar RBAC Guard"]
        AST["AST Security Sandbox"]
        DBBridge["Tenant SQLite Bridge"]
        Cedar --> AST --> DBBridge
    end

    ClaudeWeb -->|"1-Click Consent"| OAuthPKCE --> CoreEngine
    ClaudeCLI -->|"User Code (ABCD-1234)"| DeviceCode --> CoreEngine
    Cursor -->|"Direct Header"| BearerToken --> CoreEngine

A. Browser 1-Click Flow (OAuth 2.0 PKCE S256)

Designed for Claude.ai and web-based AI coding agents:

1. Claude initiates connection to https://mcp.pocket-kit.naftalmatoya.tech/oauth/authorize.
2. Pocket Kit displays the OAuth Consent Dialog, itemizing requested scopes (read, write, hooks, schema).
3. You click “Approve Access” with one click.
4. Pocket Kit issues a cryptographically signed authorization code back to Claude’s callback URL (https://claude.ai/api/mcp/auth_callback).

B. Terminal Flow (RFC 8628 Device Code)

Designed for CLI tools (like Claude Code):

1. The CLI calls /oauth/device/code and receives a user code (e.g. ABCD-1234) and verification URL.
2. The developer opens the URL, enters the 8-character code, and clicks approve.
3. The CLI automatically receives its session token without exposing raw secrets in terminal logs.

C. Direct Bearer Token

• Generate a persistent Personal MCP Token from the Remote MCP tab in your Pocket Kit Dashboard.
• Pass the token via the Authorization: Bearer fuko_mcp_... header.

---

3. Security & Safety Model

1. Strict User Scoping: MCP tokens are bound strictly to your authenticated Pocket Kit user ID and cannot inspect or mutate other developers’ databases.
2. AWS Cedar Policy Guard: Enforces fine-grained attribute-based access control (ABAC) before executing queries or schema migrations.
3. AST Static Safety Checks: All JavaScript hook modifications are statically analyzed to block unsafe system execution ($os.cmd, $os.exec) before touching disk.
4. Isolated SQLite Sandbox: Each database operation executes strictly against your single-tenant SQLite database on dedicated NVMe storage.