Connect with MCP

Use Purrkey as a remote tool server in a client that supports Streamable HTTP.

On this page

Add the server address
Choose an authentication method
Claude Code plugin
Claude Code direct setup
Cursor
Codex
Gemini CLI
Use the exposed tools
Verify the connection

Add the server address

Create a remote HTTP connection in your client's MCP settings. The endpoint is:

URL

https://api.purrkey.app/mcp

Choose an authentication method

OAuth availability depends on the server and client configuration. Do not invent a client ID or callback address. Use an API-key connection when your client supports headers and an OAuth setup is not available.

OAuth scopes are catalog:read, runs:read, runs:write and balance:read; offline_access is needed for refresh access when supported. Website sign-in tokens are not MCP credentials.

Method	What you need
API key	A client that can send Authorization: Bearer <key>. Load the key from a secret or environment variable supported by the client.
OAuth	An enabled Purrkey OAuth connection and a registered client with the exact callback URL. Complete consent in the browser when prompted.

Create a Purrkey API keyMake the key available to your client as PURRKEY_API_KEY through your shell or secret manager.

Claude Code plugin

If you have a local copy of the Purrkey marketplace, add it and install the plugin. These commands use the marketplace folder in an AgentToolX checkout; use the path to your copy if it is elsewhere.

Start Claude Code with PURRKEY_API_KEY set and check the connection with /mcp. If you do not have the marketplace files, use the direct setup below.

Terminal

claude plugin marketplace add ./integrations/claude-code
claude plugin install purrkey@purrkey-marketplace

Claude Code direct setup

Set PURRKEY_API_KEY in the environment that starts Claude Code. From your project folder, add the connection and check it with /mcp.

The single quotes preserve the variable reference so Claude Code reads the key from its environment.

Bash

claude mcp add --transport http purrkey https://api.purrkey.app/mcp --header 'Authorization: Bearer ${PURRKEY_API_KEY}'

Cursor

Set PURRKEY_API_KEY in the environment available to Cursor, then open the install link and confirm in Cursor. Restart Cursor after changing its environment.

If the link does not open Cursor, merge this server entry into your user configuration at ~/.cursor/mcp.json. Check the connection under Settings → Tools & MCP.

JSON

{
  "mcpServers": {
    "purrkey": {
      "url": "https://api.purrkey.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PURRKEY_API_KEY}"
      }
    }
  }
}

Add to CursorOpen Cursor with the Purrkey MCP connection ready to add.

Codex

With PURRKEY_API_KEY available to Codex, register the connection once. Start a new Codex session and use /mcp to check the connection.

Terminal

codex mcp add purrkey --url https://api.purrkey.app/mcp --bearer-token-env-var PURRKEY_API_KEY
codex mcp list

Gemini CLI

With PURRKEY_API_KEY available to Gemini CLI, merge this server entry into ~/.gemini/settings.json. Start Gemini CLI and use /mcp to check the connection.

JSON

{
  "mcpServers": {
    "purrkey": {
      "httpUrl": "https://api.purrkey.app/mcp",
      "headers": {
        "Authorization": "Bearer ${PURRKEY_API_KEY}"
      }
    }
  }
}

Use the exposed tools

Your client may prefix these names with its connection name. Use the tool schemas supplied by the connected server. The run arguments follow the same request shape as the HTTP API.

discover arguments · JSON

{"query":"public video comments","limit":5}

MCP tool	Input and purpose
discover	Send query and an optional limit to find candidate tools.
inspect	Send toolId and an optional toolRevision to read the exact contract.
run	Send the balance-funded Run request with inspected revisions, input, idempotencyKey and maxChargeMicros. The complete request must fit in 1 MiB after JSON string escaping and expansion of numbers to decimal form, including any tool and cache defaults.
get_run	Send the original runId to read current status and results.
cancel_run	Send the original runId to request cancellation, then check its outcome.

Run request fieldsRevisions, input, request identity and spending cap.

Verify the connection

Ask the client to list the tools exposed by the connected Purrkey server.
Discover a capability and inspect one candidate without starting a paid Run.
For a real task, keep the inspected price, a spending cap and the original Run ID.

Authentication and permissionsUnderstand account access and tool permissions.