MCP Server

MCP Overview

The kinetk MCP server is a Model Context Protocol server that wraps the heavy KINETK async-job API as agent-friendly tools. Your prompt mentions kinetk and the LLM submits real retrieval jobs, polls them, and gets back token-efficient response envelopes.

There are two ways to run it — both expose the same tools, hit the same Graph Service backend, and bill the same account:

Hosted MCP (remote)Local MCP (stdio)
What it isA managed HTTP endpoint KINETK hosts for youThe kinetk-mcp package you run as a subprocess
SetupNothing to install — sign in (OAuth) or pass an x-api-key headerClone, npm install, npm run build, point your client at dist/index.js
TransportHTTP / SSEstdio
AuthOAuth sign-in or API keyAPI key via env var
Best forClaude Desktop, ChatGPT, Claude Code, Cursor, Gemini CLI — anything that supports remote connectorsPinning a specific version, local/offline dev, custom forks
GuideHosted MCPInstallation

Most users want the Hosted MCP — there’s nothing to install. Reach for the local package when you need to pin a version or run a modified build; its source lives in mcp-server/. Per-tool reference (same for both): Tools.

What the MCP exposes

Three tools that map to the async job lifecycle:

ToolPurpose
create_context_jobSubmit either kind (records or insights). Returns { jobId, kind, status, fromCache }.
get_context_job_statusCheap poll. Returns { jobId, kind, status, submittedAt, startedAt, completedAt, error? }.
get_context_job_resultFetch the result. Defaults to a slim envelope (token-efficient); verbose: true returns the full graph-service payload.

Underneath, these talk HTTPS to the deployed Graph Service via POST /intelligence/jobs and GET /intelligence/jobs/{id}. The MCP itself is stateless — all retrieval state lives in the backend.

When to use the MCP vs the raw API

Use casePick
You’re using Claude Code, Cursor, Gemini CLI, Windsurf, or Claude Desktop and want the agent to fetch context for youMCP
You’re prototyping an agent loop that orchestrates multiple intelligence queriesMCP
You’re building a backend service, scheduled job, or dashboardRaw API
You need an endpoint the MCP doesn’t expose (e.g. /narratives/trending, /health)Raw API

The MCP intentionally surfaces only the async intelligence/jobs flow. The precomputed narrative reads (/narratives/*) and /health are direct sync reads — there’s no agent benefit to wrapping them, so they live only in the API Reference.

Why a slim envelope?

Graph-service results can be 100s of KB. AI agents pay per token, so by default the MCP returns a slim envelope per kind:

  • records: per-content rows (id, platform, title, tags, similarity, engagement, creator) plus the relationship graph.
  • insights: dense narrative insights and relationships (topTags, tagCombinations, narrativeInsights, …) plus the structured signals.

Prompting tips

The LLM doesn’t know to use the MCP unless you cue it. Two patterns work:

  1. Name the MCP: “Use kinetk to find trending content about luxury watches in the last 7 days.”
  2. Name the kind: “Submit an insights job via kinetk for luxury watch culture 2026.”

Without one of these cues, Claude/Cursor will answer from general knowledge and skip the MCP entirely — costing you nothing but giving you no real intelligence.

Transport

  • Hosted MCP speaks HTTP / SSE. Connect over OAuth sign-in or an x-api-key header — no subprocess to manage. See Hosted MCP.
  • Local MCP (kinetk-mcp) speaks stdio. Clients launch it as a subprocess and exchange JSON-RPC frames on its stdin/stdout. See Installation.