For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
kinetk.ai
DocumentationAPI Reference
  • Get Started
    • Introduction
    • Authentication
    • Quickstart
  • Guides
    • Narrative Intelligence
    • Intelligence Jobs
    • Sync & Freshness
  • MCP Server
    • Overview
    • Installation
    • Tools
kinetk.ai
On this page
  • What the MCP exposes
  • When to use the MCP vs the raw API
  • Why a slim envelope?
  • Prompting tips
  • Transport
MCP Server

MCP Overview

Was this page helpful?
Previous

MCP Installation

Next
Built with

The kinetk MCP server is a Model Context Protocol server that wraps the heavy KINETK async-job API as agent-friendly tools. AI clients (Claude, Cursor, Gemini CLI, Windsurf, …) launch it as a subprocess and call its tools over JSON-RPC — your prompt mentions kinetk and the LLM submits real retrieval jobs, polls them, and gets back token-efficient response envelopes.

Source code lives in mcp-server/ in this repo. Installation: Installation. Per-tool reference: Tools.

What the MCP exposes

Three tools that map to the async job lifecycle:

ToolPurpose
create_context_jobSubmit any of the four kinds. 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. Precomputed narrative reads (/narratives/*), /health, and the creator reads (/creators/{id}, /creators?ids=...) are direct sync reads — there’s no agent benefit to wrapping them, so they live only in the API Reference.

Why a slim envelope?

intelligence_discover results can be 100s of KB — full vectors, every content row, every analytics breakdown. AI agents pay per token, so by default the MCP returns:

  • Per-content: id, platform, title, tags, similarity, engagement, creator.
  • The narrative + tag + creator graphs (for intelligence_discover).
  • The LLM insights (for intelligence_discover).

Skipped by default: raw vectors, full retrieval diagnostics, debug breakdowns. Pass verbose: true to get_context_job_result to get the untouched payload.

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 intelligence_discover 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

The MCP currently speaks stdio only. Clients launch kinetk-mcp as a subprocess and exchange JSON-RPC frames on its stdin/stdout. Stdout is reserved for protocol frames; any logs the server emits go to stderr.

HTTP/SSE transport is planned for v2 (would unlock ChatGPT Connectors and remote use cases). Today, see Installation for the supported clients.