MCP quickstart

Gordon's MCP server lets any AI agent call paid x402 services — search, scrape, data, AI — using your agent's provisioned USDC wallet. No wallet keys in your code, no billing accounts per service.

Setup takes about 2 minutes.

Step 1

Get your agent key

1Create an account — Sign up at withgordon.ai.
2Create an agent — Go to Account → Agents → New agent. Gordon provisions a wallet on Base for the agent; copy the agent key — it's shown only once.
3Fund the agent's wallet — Open your agent and click Fund to deposit USDC on Base. Gordon blocks payments if the balance is too low.
4Review services (optional) — New agents come with the curated catalog already enabled (Exa, Zlurp, CoinGecko, …). Tighten spend caps or disable any service from the agent's Services tab. That's it.

Your agent key looks like this:

gak_pub_abc123:gak_sec_xyz789

Keep the secret half private. Treat it like a password.

Step 2

Add Gordon to your client

Pick your client below. Replace gak_pub_...:gak_sec_... with your actual key, or store it as the GORDON_AGENT_KEY environment variable.

Cursor

Open Cursor → Settings → MCP and add:

{
  "mcpServers": {
    "gordon": {
      "type": "streamable-http",
      "url": "https://api.withgordon.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${GORDON_AGENT_KEY}"
      }
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "gordon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.withgordon.ai/mcp",
        "--header",
        "Authorization: Bearer gak_pub_<id>:gak_sec_<secret>"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Other clients

VS Code, Windsurf, Codex CLI, and other MCP-compatible clients are supported — see Other clients below.

Shortcut

Let your agent install it

If you already have a coding agent open (Cursor, Claude Code, Codex, Windsurf…), paste one of these prompts directly into the chat. The agent identifies its own client, adds Gordon to the right config file, and confirms the tools load — no manual JSON editing required.

Environment-variable install recommended

This follows the same pattern as modern MCP quickstarts: the agent installs the server into its own harness, but the secret stays outside chat and config files.

Please install the Gordon MCP server so that YOU (the coding agent I'm currently talking to) can call it.

- Server URL: https://api.withgordon.ai/mcp
- Transport: Streamable HTTP
- Authentication: Bearer token — required. Format: gak_pub_…:gak_sec_…

Do NOT ask me to paste my agent key secret into the chat, and do NOT write a literal secret into a config file.
Configure the client to read the key from the GORDON_AGENT_KEY environment variable.
The Authorization header must be: Bearer ${GORDON_AGENT_KEY}

First, identify which MCP client harness you are running inside (Claude Code, Codex CLI, Cursor, VS Code Copilot,
Windsurf, Zed, etc.) — this is your OWN host. Add Gordon to THAT client's config only:

- Cursor:       ~/.cursor/mcp.json → "mcpServers": { "gordon": { "type": "streamable-http", "url": "...", "headers": { "Authorization": "Bearer ${GORDON_AGENT_KEY}" } } }
- VS Code:      .vscode/mcp.json  → "servers": { "gordon": { "type": "http", "url": "...", "headers": { "Authorization": "${env:GORDON_AGENT_KEY}" } } }
- Claude Code:  claude mcp add --transport http gordon https://api.withgordon.ai/mcp --header "Authorization: Bearer ${GORDON_AGENT_KEY}"
- Codex CLI:    ~/.codex/config.toml → [mcp_servers.gordon] command = "npx", args = ["-y", "mcp-remote", "...", "--header", "Authorization: Bearer ${GORDON_AGENT_KEY}"]
- Claude Desktop / Zed / Warp: npx mcp-remote https://api.withgordon.ai/mcp --header "Authorization: Bearer ${GORDON_AGENT_KEY}"

After the config is in place, tell me exactly what I need to do on my end to set GORDON_AGENT_KEY,
whether the harness needs a restart, and then confirm by calling gordon_list_services.

Step 3

Try it

Once your client connects, paste one of these prompts to verify everything works:

List enabled services

What services do I have enabled on Gordon?

Web search via Exa

Search the web for "x402 protocol" using Exa and summarize the top 3 results.

Scrape a page

Use Zlurp to scrape https://x402.org and give me a summary.

Payment blocked?

If you see insufficient_usdc_balance, your agent wallet needs USDC on Base. Open your agent at withgordon.ai/account/agents and click Fund to top up. If you see SERVICE_NOT_ENABLED, enable the service in the agent's Services tab first.

Reference

Available tools

Gordon exposes nine tools. Your AI client discovers them automatically — you don't need to configure tools manually.

gordon_request

Call an enabled catalog service by URL. Pass service_id and operation_id so Gordon can enforce the agent's service policy.

Example: Call Exa search by URL with service_id exa and operation_id search.web.

gordon_call_servicerecommended

Call a catalog service by name (e.g. exa, zlurp, coingecko). Gordon handles the payment, enforces your spend policy, and returns the provider response.

Example: Search for papers on agentic payments using Exa.

gordon_find_service

Look up a service from the Gordon catalog and see its operations and pricing. Useful before calling a service.

Example: What operations does Zlurp support and what do they cost?

gordon_list_services

List services in the Gordon catalog with operations and pricing.

Example: What paid services are in the catalog?

gordon_get_service

Fetch one catalog service by service_id, which can be a UUID or slug such as exa.

Example: Show me Exa operations and pricing.

gordon_list_enabled_services

List services enabled for this authenticated agent with spend limits and today's utilization.

Example: What paid services can I use right now?

gordon_get_receipt

Fetch a signed receipt for a completed payment by settlement ID.

Example: Show me the receipt for my last Exa search.

gordon_get_balance

Check this agent's USDC wallet balance and per-service daily spend remaining.

Example: Do I have enough USDC for a multi-call research run?

gordon_get_audit_log

Fetch recent service-call audit records for this agent.

Example: Show my latest paid service calls.

Other clients

VS Code, Claude Code, Codex

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "gordon": {
      "type": "http",
      "url": "https://api.withgordon.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GORDON_AGENT_KEY}"
      }
    }
  }
}

Claude Code

Install Gordon directly. If your Claude Code version does not support remote HTTP headers, use the mcp-remote fallback command.

claude mcp add --transport http gordon https://api.withgordon.ai/mcp --header "Authorization: Bearer gak_pub_<id>:gak_sec_<secret>"

# Fallback:
claude mcp add gordon -- npx -y mcp-remote https://api.withgordon.ai/mcp --header "Authorization: Bearer gak_pub_<id>:gak_sec_<secret>"

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.gordon]
command = "npx"
args = ["-y", "mcp-remote", "https://api.withgordon.ai/mcp", "--header", "Authorization: Bearer gak_pub_<id>:gak_sec_<secret>"]

Anthropic API & Claude Console

Use Gordon's MCP server directly in the Anthropic Messages API MCP connector (beta). Add these fields to your API request body and include the anthropic-beta: mcp-client-2025-11-20 header. The authorization_token is your raw agent key — Anthropic injects the Bearer prefix automatically.

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://api.withgordon.ai/mcp",
      "name": "gordon",
      "authorization_token": "gak_pub_<id>:gak_sec_<secret>"
    }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "gordon" }
  ]
}

Python SDK example:

import anthropic, os
# export GORDON_AGENT_KEY="gak_pub_<id>:gak_sec_<secret>"

client = anthropic.Anthropic()
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    mcp_servers=[{
        "type": "url",
        "url": "https://api.withgordon.ai/mcp",
        "name": "gordon",
        "authorization_token": os.environ["GORDON_AGENT_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "gordon"}],
    messages=[{"role": "user", "content": "What services are available?"}],
    betas=["mcp-client-2025-11-20"],
)
print(response.content)

In the Claude Console Workbench, add an MCP server with URL https://api.withgordon.ai/mcp and paste your agent key as the authorization token.

Windsurf, Zed, Warp, and other stdio-only clients

Use mcp-remoteas the local stdio bridge to Gordon's Streamable HTTP endpoint:

npx -y mcp-remote https://api.withgordon.ai/mcp --header "Authorization: Bearer gak_pub_<id>:gak_sec_<secret>"