MCP Tools & Capabilities

Reference for all 14 tools and 5 prompts KoKo exposes over MCP. Need help connecting a client? See MCP Clients. Prefer traditional HTTP? See the REST API.

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

Tools (14) Prompts (5) 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")

Troubleshooting

Connection or authentication problems? See MCP Clients troubleshooting.

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).