Connect a Client

Point your client at /console/mcp for your own account, or /checkout/mcp for a customer-facing agent. Both live on the same deployment.

Authentication

Every request carries its own key. The server holds no credentials of its own — no .env, no shared key, nothing stored — which is what lets one deployment serve a whole team: each caller's key identifies their account.

Authorization: Bearer snp_your_api_key_here

Key types

Prefix	Kind	Can do
`snp_`	API key	Everything — mobile-money USSD push, payment links, and reads
`plk_`	Link key	Payment links and sessions only. Cannot trigger a mobile-money push

create_mobile_payment needs the collection:create scope, which only snp_ keys carry. Given a plk_ key, the server hides that tool from the client's tool list and rejects it if called anyway. See Authentication for generating keys and choosing scopes.

Headers

Header	Required	Purpose
`Authorization: Bearer <key>`	Yes	The caller's Snippe key. Identifies the account and decides what the agent can do.
`X-Webhook-Url`	For `create_mobile_payment`; recommended for links	Where Snippe posts `payment.*` events. Every payment inherits it.
`X-Metadata`	No	Base metadata (a JSON object) merged into every payment and session. Per-call keys win.

You set these once in your client config. The model never handles them: no tool takes a key, a webhook URL, or an account identifier as a parameter.

A call with no key fails with Missing Snippe API key. A create_mobile_payment call with no X-Webhook-Url is refused before it reaches the API — set the header rather than retrying.

Client configuration

claude mcp add --transport http snippe https://mcp.yourdomain.com/console/mcp \
  --header "Authorization: Bearer snp_your_api_key_here" \
  --header "X-Webhook-Url: https://yoursite.com/webhooks/snippe"

Add --scope project to share the server with everyone working in the repo — but keep the key in an environment variable if that config is committed.

Edit your config file:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "snippe": {
      "url": "https://mcp.yourdomain.com/console/mcp",
      "headers": {
        "Authorization": "Bearer snp_your_api_key_here",
        "X-Webhook-Url": "https://yoursite.com/webhooks/snippe"
      }
    }
  }
}

Restart Claude Desktop. Snippe appears in the tools menu.

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json to enable it everywhere:

{
  "mcpServers": {
    "snippe": {
      "url": "https://mcp.yourdomain.com/checkout/mcp",
      "headers": {
        "Authorization": "Bearer plk_your_link_key_here"
      }
    }
  }
}

Your client launches the server as a subprocess and talks to it over stdin/stdout — nothing listens on a port. A single stdio channel can't serve two servers, so it exposes Console, the superset of tools.

uv run snippe-mcp

The key travels in a request header, and a stdio subprocess has no HTTP request to carry one — so tool calls over stdio come back with Missing Snippe API key. Use stdio to inspect the tool list locally; use the HTTP transport for anything that talks to the API.

Troubleshooting

Every call returns 401. The Authorization header isn't reaching the server. Check the client is sending it, and that your proxy passes it through. The server log tells you which: it records whether a Bearer header arrived at each endpoint.

Every call returns Missing Snippe API key. Same cause — or you're on stdio, which has no header to carry the key.

create_mobile_payment isn't in the tool list. You connected with a plk_ link key. Link keys can't trigger a USSD push; use create_payment_link, or reconnect with an snp_ key.

Missing webhook URL. Set X-Webhook-Url in your client config. Payments require it.

The server doesn't appear at all. Restart the client fully, then confirm the deployment is up by hitting /health.

Calls fail with 429. You've hit a rate limit — the MCP edge or the API. Back off; see Error Handling.