← Back to Home

KoKo Developer API

Access KoKo's credit card intelligence through the Model Context Protocol (MCP). Connect your AI assistant to search, compare, and analyze 100+ credit cards in real time.

MCP Endpoint https://koko-backend-925873984649.us-central1.run.app/mcp/

Available Tools

KoKo exposes 7 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)

`compare_cards`

Compare 2-3 credit cards side by side with AI-powered analysis. Optionally provide spending data for personalized winner recommendations.

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}

`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. Determines whether the annual fee is worth it.

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. Returns a session_id to pass to other tools for portfolio persistence.

Parameter	Type	Required	Description
No parameters required

`optimize_portfolio`

Analyze your credit card portfolio and get optimization strategies. Returns a health score, net value, KEEP/OPTIMIZE/CANCEL verdicts for each card, and actionable strategies.

Parameter	Type	Required	Description
`card_names`	list[string]	Yes	List of credit card names you own
`monthly_spending`	object	No	Monthly spending by category ($)
`session_id`	string	No	Session ID from create_mcp_session (auto-created if omitted)

`recommend_card_for_category`

Recommend which card from your portfolio to use for a specific spending category. Analyzes rewards structures to maximize your value.

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)
`session_id`	string	No	Session ID from create_mcp_session (auto-created if omitted)

Usage Examples

Once connected, users can ask their AI assistant natural questions. Here are example prompts and the tools that get called behind the scenes.

Example 1: Finding the Right Card

"I spend about $500/month on groceries and $300 on dining out. What's the best credit card for me?"

The AI calls search_credit_cards with the natural language query, then presents the top matches with annual fees, rewards rates, and why each card fits.

Tool: search_credit_cards
Params: {
  "query": "best card for groceries and dining $500 groceries $300 dining",
  "max_results": 3
}

Returns: Cards ranked by fit score with annual_fee, key_benefits,
why_recommended, and apply_url for each match.

Example 2: Comparing Cards Before Applying

"Compare the Chase Sapphire Preferred vs the Amex Gold Card. I spend mostly on dining and travel."

The AI calls compare_cards with spending data to provide a side-by-side analysis and declare a winner.

Tool: compare_cards
Params: {
  "card_names": ["Chase Sapphire Preferred", "Amex Gold"],
  "monthly_spending": {"dining": 400, "travel": 300}
}

Returns: Side-by-side comparison with rewards analysis,
winner recommendation, and best use case for each card.

Example 3: Optimizing an Existing Portfolio

"I have the Chase Sapphire Reserve, Amex Gold, and Citi Double Cash. Should I keep all of them? Which should I use for groceries?"

The AI calls optimize_portfolio for a health score and KEEP/CANCEL verdicts, then recommend_card_for_category to identify the best card for groceries.

Tool 1: optimize_portfolio
Params: {
  "card_names": ["Chase Sapphire Reserve", "Amex Gold", "Citi Double Cash"]
}

Returns: Health score, net annual value, verdict per card
(KEEP/OPTIMIZE/CANCEL), top strategies, and quick wins.

Tool 2: recommend_card_for_category
Params: {
  "card_names": ["Chase Sapphire Reserve", "Amex Gold", "Citi Double Cash"],
  "category": "groceries",
  "session_id": "mcp_abc123def456"
}

Returns: Best card for groceries with explanation,
alternatives ranked, and pro tips.

Example 4: Is This Annual Fee Worth It?

"I'm thinking about the Chase Sapphire Reserve. I spend about $30,000 a year. Is the $550 annual fee worth it?"

The AI calls get_card_details for full card info, then calculate_card_value for the break-even analysis.

Tool 1: get_card_details
Params: { "card_name": "Sapphire Reserve", "issuer": "Chase" }

Returns: Full card details including rewards structure,
key benefits, welcome bonus, and apply URL.

Tool 2: calculate_card_value
Params: {
  "annual_spending": 30000,
  "annual_fee": 550,
  "sign_on_bonus": 60000,
  "sign_on_bonus_type": "points"
}

Returns: First-year value, ongoing annual value,
break-even spend, and verdict.

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://koko-backend-925873984649.us-central1.run.app/mcp/

ChatGPT & Other AI Assistants

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

Endpoint:  https://koko-backend-925873984649.us-central1.run.app/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://koko-backend-925873984649.us-central1.run.app/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"}
    }
  }'

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.

Connecting from Claude Desktop

Add the server URL to your Claude Desktop configuration. On first use, a browser window will open for Google sign-in.

Server URL: https://kokofinance.net/mcp

Connecting from Claude.ai

Go to Settings → Integrations and add the MCP server URL. Claude.ai will handle the OAuth connection automatically.

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://koko-backend-925873984649.us-central1.run.app/.well-known/mcp.json

This returns the server name, endpoint URL, transport type, authentication requirements, and a list of all available tools.

Troubleshooting

Common issues and how to resolve them.

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.

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". Common abbreviations like "Amex" and "BoA" are supported.
Compare or portfolio tool returns partial results	Ensure card names are spelled correctly. Use `search_credit_cards` first to find the exact card name in our database.
Tool call times out	Some tools (like search) query external data sources and may take a few seconds. Try again — if the issue persists, the server may be cold-starting (first request after idle takes ~10 seconds).

Verifying Server Status

You can check that the MCP server is running and responding correctly:

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

# Check OAuth discovery endpoint
curl https://kokofinance.net/mcp/.well-known/oauth-authorization-server

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

If any of these fail, please contact us.

Questions or Feedback?

We'd love to hear how you're using KoKo with your AI assistant.