Connect to Kunkafa

Connect Kunkafa once in your AI app. Sign up or sign in and approve access in your browser, then return to the conversation to explore your market and continue your learning and research.

MCP is included in Free, Starter, Core, Pro and Publisher. It uses your account’s current market access and shared allowances. Free, Starter and Core each allow 1 connection; Pro allows 5 and Publisher 20. MCP connections and personal API tokens share this connection limit. Adding a connection does not add another summary allowance.

REST API is included in Pro and Publisher. Each forecast request reads one market, up to 6 durations and 72 forecasts; requests from one connection can run at the same time. Pro follows 10 markets and Publisher includes every market. Every published duration is included.

In Account → API & MCP connections, choose Create API token. Give it a recognizable name and select only the permissions you need. The token is shown once and expires after 90 days.

Keep the token in your application’s secret storage. Send it in the Authorization: Bearer header. Never put it in a URL, public website bundle, screenshot, support message or shared source file. The example below assumes KUNKAFA_TOKEN is already set securely.

curl --fail-with-body \
  --header "Authorization: Bearer ${KUNKAFA_TOKEN}" \
  "https://kunkafa.com/api/v1/usage"

The read scopes are markets:read, outlooks:read, performance:read, results:read and usage:read; following:write follows and unfollows markets. A token must include the scope for its requested operation, and each MCP tool declares its scope in securitySchemes. Token permissions never extend your account’s market or plan access.

Market and usage lists are paginated. Follow page.nextCursor until it is null; do not assume the first page contains every permitted market. The default page size is 50, which is also the maximum. Restart without a cursor if access or market names change.

Use authorization code flow with PKCE and resource https://kunkafa.com/mcp. Discovery starts at https://kunkafa.com/.well-known/oauth-protected-resource/mcp; the authorization issuer is https://kunkafa.com/oauth. Use the endpoints returned by discovery and validate the issuer, resource and audience. Claude connects with its published client identity (a Client ID Metadata Document), so it does not register; other apps can register dynamically.

Access tokens expire after 10 minutes. Refresh tokens rotate and reuse invalidates the connection’s grant. An MCP connection stays connected while it is used: it expires after 90 days without use, and at most one year after approval. Approving the same app again replaces its connection without using another one; if it asks only for access already allowed, Kunkafa approves it without a second screen. A connection without a permission a tool needs gets an insufficient_scope challenge, so the app can ask you for it. Each tool declares its permission in securitySchemes, and get_usage shows the connection’s permissions and expiry. Refreshing a token does not change the active integration session.

REST requires an API token from a Pro or Publisher account. Use GET for discovery, usage and the published record; use POST with a JSON body containing market and durations (or minDuration and maxDuration) for current forecasts; use POST /api/v1/following and DELETE /api/v1/following/{slug} to follow and unfollow (following:write). Plans and account links need no token. Replace {slug} with the market value returned by discovery. Replies are in English.

GET  https://kunkafa.com/api/v1/glossary
GET  https://kunkafa.com/api/v1/markets
POST https://kunkafa.com/api/v1/outlooks
GET  https://kunkafa.com/api/v1/markets/{slug}/performance
GET  https://kunkafa.com/api/v1/markets/{slug}/results
GET  https://kunkafa.com/api/v1/usage
POST https://kunkafa.com/api/v1/following
DELETE https://kunkafa.com/api/v1/following/{slug}
GET  https://kunkafa.com/api/v1/plans
GET  https://kunkafa.com/api/v1/account-links

get_glossary

Glossary

What every Kunkafa term and number means and how to read them. Call once before explaining results. No sign-in needed.

list_markets

Available markets

Markets this account can read, each with the durations that have forecasts now, and what it follows. Page with page.nextCursor.

follow_market

Follow a market

Follow a market for this account. Check canFollow in get_usage first. Replacing a followed market is allowed once every 30 days: ask the user, then call with confirmReplacement true.

unfollow_market

Unfollow a market

Stop following a market; its data stops being readable. Check canFollow in get_usage first.

get_outlooks

Current forecasts

Current forecasts for one market; one market per call by design, so data is not pulled in bulk. Choose durations (exact or a range) and optionally direction, confidence or target filters. At most 6 durations and 72 forecasts per call; calls can run in parallel.

get_performance

Past performance

How often past forecasts touched their target, by confidence level and period. Pass probabilityPercent for the matching row (headline).

get_results

Past results

Recent example forecasts with their outcomes; not a full record.

get_usage

Usage and limits

Remaining allowances, what one get_outlooks call returns, and this connection's permissions, canFollow and expiry. Uses no allowance.

Every tool declares the format of its reply, the same format as the REST API reference.

get_account_links provides official Kunkafa links for account creation, sign-in and account management. It does not require an account. For more information, visit kunkafa.com.