MCP Clients - Koko Finance Developer Docs

Get the Full Experience

Two clients bundle the MCP tools and KoKo's credit card advisor skill into a single install — no manual server configuration needed.

Claude Code Plugin

Install the KoKo plugin for Claude Code to get both the MCP tools and an expert credit card advisor skill.

git clone https://github.com/KokoFinance/koko-credit-card-plugin.git
claude --plugin-dir ./koko-credit-card-plugin

See the plugin repository for details.

Cursor Plugin

KoKo Finance is published in the Cursor Directory as koko-credit-cards — it bundles the same MCP tools and advisor skill as the Claude Code plugin.

Open the listing and click Install.

MCP Server Only

Prefer to configure the bare server yourself, or using a client without a bundled plugin? Not every MCP client supports the OAuth + Dynamic Client Registration flow yet — clients that do get one-click Google sign-in; clients that don't use a static API key instead.

OAuth — no key needed

Claude Desktop

Go to Settings → Connectors and add a new MCP server with this URL:

https://kokofinance.net/mcp

Click Connect — a browser window will open for Google sign-in. Once authenticated, KoKo tools are available in your conversations.

Claude Code (CLI)

Add KoKo as an MCP server with a single command:

claude mcp add --transport http koko-credit-cards https://kokofinance.net/mcp/

ChatGPT / OpenAI

KoKo Finance is available as an MCP plugin in ChatGPT. Once approved in the OpenAI directory, you can enable it from Settings → Connected Apps.

Authentication is handled via Google sign-in during the connection flow — no API key needed.

API key required

OpenAI Codex

Connect Codex to KoKo using an API key. In your Codex MCP configuration, add:

{
  "mcpServers": {
    "koko-finance": {
      "url": "https://kokofinance.net/mcp/",
      "headers": {
        "Authorization": "Bearer koko_your_api_key_here"
      }
    }
  }
}

Get your API key from the Developer Dashboard (free tier includes 1,000 calls total, a one-time evaluation quota).

Cursor, Cline & Other AI Assistants

If your AI assistant supports MCP servers directly (without installing the plugin above), configure it with:

Endpoint:  https://kokofinance.net/mcp/
Transport: Streamable HTTP
Auth:      Bearer koko_your_api_key_here
Protocol:  MCP 2025-03-26

Pass the API key via the Authorization: Bearer koko_... header or X-API-Key header, depending on your client.

Direct HTTP (JSON-RPC)

Advanced: raw protocol

Send MCP JSON-RPC requests directly via HTTP POST:

curl -X POST \
  https://kokofinance.net/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "MyApp", "version": "1.0"}
    }
  }'

MCP Authentication

KoKo's MCP server supports two authentication methods:

OAuth 2.0 (Google) — used by Claude.ai, Claude Desktop, and ChatGPT. The client handles the sign-in flow automatically.
API Key — used by Codex, Cursor, Cline, and programmatic clients. Pass your key via Authorization: Bearer koko_... or X-API-Key: koko_... header.

OAuth Discovery

For programmatic clients, the OAuth authorization server metadata is available at:

GET https://kokofinance.net/mcp/.well-known/oauth-authorization-server

Auto-Discovery

KoKo supports the MCP auto-discovery standard. AI clients can find our server configuration at:

GET https://kokofinance.net/.well-known/mcp.json

API Key Authentication (for Usage Tracking)

MCP access works via OAuth (Google sign-in) or API key. OAuth users are automatically provisioned with an evaluation tier account (1,000 calls included) — the same quota as API key users. All calls count against your tier quota (same pool as REST API calls).

To use an API key instead of OAuth, pass it via the X-API-Key header in your MCP transport configuration:

Claude Desktop Configuration

{
  "mcpServers": {
    "koko-finance": {
      "url": "https://kokofinance.net/mcp/",
      "headers": {
        "X-API-Key": "koko_your_api_key_here"
      }
    }
  }
}

Claude Code CLI

claude mcp add --transport http \
  --header "X-API-Key: koko_your_api_key_here" \
  koko-credit-cards https://kokofinance.net/mcp/

When you hit your monthly limit, MCP tool responses will include an error with a link to upgrade. Check your usage at any time with GET /api/v1/usage.

Troubleshooting

OAuth / Authentication Errors

Symptom	Solution
"Please check your server URL and make sure your server handles auth correctly"	Verify you're using `https://kokofinance.net/mcp` (no trailing slash). Remove and re-add the server in Settings → Connectors.
Google sign-in window doesn't appear	Check your browser's pop-up blocker. The OAuth flow opens a new window for Google sign-in.
Previously connected but now getting auth errors	OAuth tokens may have expired. Remove the server from Connectors and re-add it to re-authenticate.
`authentication_required` error in tool response	Your MCP client is not sending credentials. Ensure OAuth is configured or include an `X-API-Key` header in your transport configuration.

Verifying Server Status

# Check server health
curl https://kokofinance.net/health

# Check MCP auto-discovery
curl https://kokofinance.net/.well-known/mcp.json

# Check REST API health
curl https://kokofinance.net/api/v1/health