← 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

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "koko-credit-cards": {
      "url": "https://koko-backend-925873984649.us-central1.run.app/mcp/",
      "transport": "streamable-http"
    }
  }
}

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.

Questions or Feedback?

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