MCP Server

Already using Claude, Cursor, or another AI client? Connect via MCP instead of REST. The MCP server provides 14 tools and 5 workflow prompts. Prefer traditional HTTP? See the REST API.

MCP calls count against the same monthly quota as REST API calls.

Tools (14) Prompts (5) How to Connect Authentication Troubleshooting

Available Tools

KoKo exposes 14 tools through MCP. Each tool returns structured JSON data that AI assistants can interpret and present to users.

`search_credit_cards`

Search for credit cards using natural language. Supports queries like "best travel card under $200 annual fee" or "cashback card for groceries."

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`max_results`	integer	No	Max cards to return (1-10, default 5)
`card_type`	string	No	Filter: travel, cashback, business, etc.
`issuer`	string	No	Filter by issuer name
`max_annual_fee`	integer	No	Maximum annual fee ($)
`credit_tier`	string	No	poor, fair, good, or excellent

`compare_cards`

Compare 2-3 credit cards side by side with fees, rewards, net value, and break-even analysis (<100ms).

Parameter	Type	Required	Description
`card_names`	list[string]	Yes	2-3 card names to compare
`monthly_spending`	object	No	Monthly spend by category, e.g. {"dining": 500, "travel": 300}
`credit_tier`	string	No	poor, fair, good, or excellent
`primary_goal`	string	No	maximize_rewards, minimize_fees, travel_perks, simplicity, or build_credit
`issuer_preferences`	list[object]	No	e.g. [{"issuer": "Chase", "weight": 0.8}]
`benefit_selections`	list[string]	No	Benefit keys the user uses (100%/0% model)

`get_card_details`

Get comprehensive details about a specific credit card including annual fee, rewards structure, benefits, welcome bonus, and application URL.

Parameter	Type	Required	Description
`card_name`	string	Yes	Card name (partial names work, e.g. "Sapphire Preferred")
`issuer`	string	No	Issuer name to narrow results (e.g. "Chase")

`calculate_card_value`

Calculate the financial value and break-even point of a credit card based on your spending. Uses conservative calculation assumptions included in the response under the assumptions key.

Parameter	Type	Required	Description
`annual_spending`	number	Yes	Total annual spending on this card ($)
`annual_fee`	number	Yes	Card's annual fee ($)
`sign_on_bonus`	number	No	Sign-on bonus amount (default 0)
`sign_on_bonus_type`	string	No	"points", "cash", or "multiplier" (default "points")

`create_mcp_session`

Create a session for tracking your credit card analysis across multiple tool calls.

Parameter	Type	Required	Description
No parameters required

`optimize_portfolio`

Analyze your credit card portfolio with health score, net value, and KEEP/OPTIMIZE/CANCEL verdicts for each card (<100ms).

Parameter	Type	Required	Description
`card_names`	list[string]	Yes	List of credit card names you own
`monthly_spending`	object	No	Monthly spending by category ($)
`point_balances`	list[object]	No	Points/miles balances: `[{"program": "chase_ur", "balance": 80000}]`
`benefit_selections`	list[string]	No	Benefit keys you use: `["uber", "dining", "admirals_club"]`
`credit_tier`	string	No	poor, fair, good, or excellent
`primary_goal`	string	No	maximize_rewards, minimize_fees, travel_perks, simplicity, or build_credit
`issuer_preferences`	list[object]	No	Boost/de-boost issuers
`cancel_threshold`	number	No	Net value below this = CANCEL (default -50)
`keep_threshold`	number	No	Net value above this = KEEP (default 50)
`session_id`	string	No	Session ID from create_mcp_session

`check_card_renewal`

Check whether to renew a credit card when the annual fee comes due. Returns a RENEW, DOWNGRADE, or CANCEL_AND_REPLACE verdict with downgrade options and replacement suggestions.

Parameter	Type	Required	Description
`card_name`	string	Yes	The card to evaluate (e.g. "Chase Sapphire Reserve")
`monthly_spending`	object	No	Monthly spending by category ($)
`other_cards`	list[string]	No	Other cards you own for portfolio context
`benefit_selections`	list[string]	No	Benefit keys you use
`benefit_categories_used`	list[string]	No	Alternative: category names instead of individual keys
`credit_tier`	string	No	poor, fair, good, or excellent
`primary_goal`	string	No	maximize_rewards, minimize_fees, travel_perks, simplicity, or build_credit
`acquired_date`	string	No	Date card was acquired (YYYY-MM-DD) for anniversary-aware analysis
`renewal_cancel_threshold`	number	No	Net value below this = CANCEL (default -100)
`renewal_keep_threshold`	number	No	Net value above this = RENEW (default 50)
`session_id`	string	No	Session ID from create_mcp_session

`recommend_card_for_category`

Recommend which card from your portfolio to use for a specific spending category, ranked by reward value (<100ms).

Parameter	Type	Required	Description
`card_names`	list[string]	Yes	List of credit card names you own
`category`	string	Yes	One of: groceries, dining, travel, gas, online_shopping, everything_else
`amount`	number	No	Purchase amount in dollars (default $100)
`credit_tier`	string	No	poor, fair, good, or excellent
`primary_goal`	string	No	maximize_rewards, minimize_fees, travel_perks, simplicity, or build_credit
`issuer_preferences`	list[object]	No	Boost/de-boost issuers
`session_id`	string	No	Session ID from create_mcp_session

`which_card_at_merchant`

Find the best card from your portfolio for a purchase at a specific merchant. Auto-detects the spending category from the merchant name (e.g. Starbucks → dining). Deterministic for 350+ known merchants; uses AI fallback for unknown merchants.

Parameter	Type	Required	Description
`merchant`	string	Yes	Merchant name (e.g. "Starbucks", "Saks Fifth Avenue")
`amount`	number	No	Purchase amount in dollars (default $100)
`card_names`	list[string]	Yes	Card names in your portfolio

`check_merchant_benefits`

Check if any cards in your portfolio have credits or benefits at a specific merchant. Returns matching credits with value, frequency, and schedule, plus an earning recommendation.

Parameter	Type	Required	Description
`merchant`	string	Yes	Merchant name (e.g. "Saks Fifth Avenue", "Uber")
`card_names`	list[string]	Yes	Card names in your portfolio

`get_card_benefits`

Get all credits, benefits, and rewards multipliers for a specific card. Returns structured data with value, frequency, schedule, and conditions for each credit.

Parameter	Type	Required	Description
`card_name`	string	Yes	Card name (e.g. "Amex Platinum", "Amex Gold")

`get_card_terms`

Get APR, penalty fees, and grace period (Schumer Box data) for a credit card. Supports fuzzy name matching.

Parameter	Type	Required	Description
`card_name`	string	Yes	Card name (e.g. "Chase Sapphire Reserve")
`issuer`	string	No	Issuer name to narrow results

`get_card_changes`

Get recent changes to a card's data (fee increases, benefit additions/removals, rewards multiplier changes). Draws from the append-only audit log.

Parameter	Type	Required	Description
`card_name`	string	Yes	Card name (e.g. "Chase Sapphire Preferred")
`issuer`	string	No	Issuer name to narrow results
`since_days`	integer	No	Look back N days (default 90)
`field`	string	No	Filter by field name (e.g. "annual_fee")

`get_program_trends`

Get valuation trends for a points program — portal CPP changes, transfer partner ratio changes, and partner additions/removals over time.

Parameter	Type	Required	Description
`program_key`	string	Yes	Program key (e.g. "chase_ur", "amex_mr")
`since_days`	integer	No	Look back N days (default 90)

MCP Prompts

5 pre-built workflow templates that guide your AI assistant through common credit card tasks.

`portfolio-review`

Analyze your credit card portfolio with health score, card-by-card verdicts (KEEP/OPTIMIZE/CANCEL), and optimization strategies.

Parameter	Type	Required	Description
`card_names`	string	Yes	Comma-separated list of card names you own
`monthly_spending`	string	No	Monthly spending by category, e.g. "dining: 500, groceries: 400"

`which-card`

Find out which card from your wallet to use for a specific purchase or spending category to maximize your rewards.

Parameter	Type	Required	Description
`card_names`	string	Yes	Comma-separated list of card names you own
`category`	string	Yes	One of: groceries, dining, travel, gas, online_shopping, everything_else
`amount`	string	No	Purchase amount in dollars (default $100)

`new-card-finder`

Find the best new credit card based on your spending habits, fee tolerance, and credit score.

Parameter	Type	Required	Description
`spending_focus`	string	Yes	Your primary spending category (e.g. "travel and dining")
`annual_fee_limit`	string	No	Maximum annual fee you'd consider (default "no limit")
`credit_score`	string	No	Your credit score range (e.g. "good", "excellent")

`renewal-check`

Check whether to renew a credit card when the annual fee comes due. Get a RENEW, DOWNGRADE, or CANCEL_AND_REPLACE verdict with value analysis and retention tips.

Parameter	Type	Required	Description
`card_name`	string	Yes	The card to evaluate (e.g. "Chase Sapphire Reserve")
`monthly_spending`	string	No	Monthly spending by category, e.g. "dining: 500, groceries: 400"
`other_cards`	string	No	Comma-separated list of other cards you own

`card-risk-assessment`

Comprehensive risk assessment for a credit card. Chains card terms (APR, penalties), recent data changes, and program valuation trends into a single analysis. Ideal for debt optimization and credit health products.

Parameter	Type	Required	Description
`card_name`	string	Yes	Card name to assess (e.g. "Chase Sapphire Reserve")

How to Connect

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/

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, Cline & Other AI Assistants

If your AI assistant supports MCP servers, configure it with:

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

Direct HTTP (JSON-RPC)

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 uses OAuth 2.0 (Google) for authentication. MCP-compatible clients like Claude.ai and Claude Desktop handle the OAuth flow automatically — you'll be prompted to sign in with Google when you first connect.

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 a free tier account (2,000 calls/month) — the same quota as API key users. All MCP calls count against your monthly 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.

Tool Errors

Symptom	Solution
"Card not found" for a card you know exists	Try using the full card name with issuer, e.g. "Chase Sapphire Preferred" instead of just "Sapphire Preferred".
Tool call times out	Some tools query external data sources and may take a few seconds. If the issue persists, the server may be cold-starting (~10 seconds).

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