MCP Setup

Overview

Pons exposes a Model Context Protocol server via Streamable HTTP transport. If your MCP client supports OAuth, use dynamic client registration first. API keys are still supported as the fallback path for clients that only accept a static bearer token.

1. Recommended: OAuth Dynamic Client Registration

If your MCP client supports OAuth and dynamic client registration, you can use the same MCP endpoint without creating an API key first.

MCP resource: https://pons.chat/api/mcp
Protected resource metadata: https://pons.chat/api/auth/.well-known/oauth-protected-resource
Authorization server metadata: https://pons.chat/api/auth/.well-known/oauth-authorization-server
Authorization endpoint: https://pons.chat/api/auth/mcp/authorize
Token endpoint: https://pons.chat/api/auth/mcp/token
Client registration endpoint: https://pons.chat/api/auth/mcp/register
JWKS: https://pons.chat/api/auth/mcp/jwks

The MCP route advertises the protected resource metadata via WWW-Authenticate, so compliant clients can usually start from https://pons.chat/api/mcp and discover the OAuth flow automatically.

During authorization, Pons will:

Redirect you to Facebook sign-in
Show a consent screen listing the requested scopes
Issue OAuth access and refresh tokens for the registered MCP client

When To Use OAuth Instead Of API Keys

Use OAuth DCR when your MCP client can manage:

dynamic client registration
authorization-code + refresh-token flows
browser sign-in and consent handoff

Use API keys when you want the simplest setup or your MCP client only supports static bearer tokens.

Discovery

A compliant MCP client can start from the MCP resource URL:

https://pons.chat/api/mcp

If the request is unauthenticated, Pons responds with a WWW-Authenticate header pointing to:

https://pons.chat/api/auth/.well-known/oauth-protected-resource

That metadata in turn points the client at the Pons authorization server and JWKS.

Dynamic Client Registration

Pons accepts standard OAuth client registration at:

POST https://pons.chat/api/auth/mcp/register

Typical registration body:

{
  "client_name": "Cursor",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "scope": "openid profile email offline_access read write send"
}

Pons supports these MCP-related scopes:

read
write
send
messages:read
messages:write
conversations:read
templates:read

It also supports the standard OAuth scopes used by MCP clients:

openid
profile
email
offline_access

Authorization Flow

After registration, the MCP client sends the user to:

GET https://pons.chat/api/auth/mcp/authorize

Expected flow:

The client starts an authorization-code flow for the resource https://pons.chat/api/mcp
Pons redirects the user to Facebook sign-in if they are not already signed in
Pons shows a consent screen at /oauth/consent
Pons redirects back to the client with an authorization code

Token Exchange

The client exchanges the authorization code at:

POST https://pons.chat/api/auth/mcp/token

Pons returns:

an access token for https://pons.chat/api/mcp
a refresh token when offline_access is requested

Access tokens issued by Pons are validated against:

https://pons.chat/api/auth/mcp/jwks

2. Optional: API Keys

Create an API key if your MCP client does not support OAuth DCR or if you want a simple static bearer token.

Sign in to pons.chat
Click the key icon in the top navigation bar to open the API Key Manager
Click Create Key
Choose a name and select the scopes you need:
- read — list conversations, search messages, view templates
- write — send reactions, archive/unarchive conversations
- send — send text and template messages
Copy the key — it won't be shown again

Add this to your MCP configuration:

{
  "mcpServers": {
    "pons": {
      "url": "https://pons.chat/api/mcp",
      "headers": {
        "Authorization": "Bearer pons_your_api_key_here"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pons": {
      "url": "https://pons.chat/api/mcp",
      "headers": {
        "Authorization": "Bearer pons_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Open Cursor Settings > MCP Servers > Add Server. Use:

Type: HTTP
URL: https://pons.chat/api/mcp
Headers: Authorization: Bearer pons_your_api_key_here

Or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pons": {
      "url": "https://pons.chat/api/mcp",
      "headers": {
        "Authorization": "Bearer pons_your_api_key_here"
      }
    }
  }
}

OpenCode

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "pons": {
      "type": "remote",
      "url": "https://pons.chat/api/mcp",
      "headers": {
        "Authorization": "Bearer pons_your_api_key_here"
      }
    }
  }
}

Any MCP Client

Pons uses Streamable HTTP transport at https://pons.chat/api/mcp. Pass the API key as a Bearer token in the Authorization header. No stdio, no SSE — just standard HTTP.

What The MCP Server Accepts

The Pons MCP endpoint accepts both of these in parallel:

Authorization: Bearer <oauth access token> for OAuth clients using DCR
Authorization: Bearer pons_... for existing API keys

That means you can adopt OAuth-capable MCP clients without breaking existing API-key integrations.

3. Verify

Ask your AI assistant:

"List my WhatsApp conversations"

It should call the list_conversations tool and return your recent chats.

Scopes

API keys and OAuth access tokens use the same MCP scopes to control what your AI can do:

Scope	Permissions
read	`list_conversations`, `list_unanswered`, `get_conversation`, `search_messages`, `list_templates`
write	`send_reaction`, `updateConversation`
send	`send_text`, `send_template`, `send_media`

Create separate keys with different scopes for different use cases. For example, a read-only key for monitoring dashboards, and a full-access key for your personal AI assistant.