MCP Tools

The kinetk MCP exposes three tools that map to the async-job lifecycle.

create_context_job

Submit an async job. Pick kind based on the analysis depth you want:

Input

• intelligence_search and intelligence_discover require query (string).
• campaign_brief and llm_context require campaign (string — the campaign name).

Common filters (work across all kinds):

Returns

1
{
2
  "jobId": "0190bd6f-1234-7abc-8def-9876543210ab",
3
  "kind": "intelligence_discover",
4
  "status": "queued",
5
  "fromCache": false
6
}

If the backend has a fresh cached run for this input, status is succeeded and fromCache: true — get_context_job_result returns in O(1) on the next call.

Example agent prompt

Use kinetk to submit an intelligence_discover job for luxury watch culture 2026 on TikTok and Instagram over the last 30 days.

get_context_job_status

Cheap poll. Pass the jobId you got from create_context_job.

Returns

1
// running
2
{ "jobId": "...", "kind": "intelligence_discover", "status": "running",
3
  "submittedAt": 1745859300000, "startedAt": 1745859302100 }
4
5
// completed
6
{ "jobId": "...", "kind": "intelligence_discover", "status": "completed",
7
  "submittedAt": ..., "startedAt": ..., "completedAt": 1745859315400 }
8
9
// failed
10
{ "jobId": "...", "status": "failed",
11
  "error": "embedding service failed (403): permission denied",
12
  "submittedAt": ..., "startedAt": ..., "completedAt": ... }

Status values: queued | running | completed | failed. Latency: ~300 ms — safe to poll every 2–5 seconds.

get_context_job_result

Fetch the result. Defaults to the slim envelope (token-efficient).

Inputs

Returns (slim envelope)

1
{
2
  "content": [
3
    {
4
      "id": "uuid",
5
      "platform": "TIKTOK",
6
      "title": "...",
7
      "tags": ["smartwatch", "fitness"],
8
      "similarity": 0.81,
9
      "engagement": 12500,
10
      "creator": { "id": 42, "handle": "fitfam_lisa", "platform": "TIKTOK" }
11
    }
12
  ],
13
  "narratives": [ /* intelligence_discover only */ ],
14
  "insights": [ /* intelligence_discover only */ ]
15
}

Skipped by default: raw vectors, full retrieval diagnostics, debug breakdowns.

Returns (verbose)

The full QueryNarrativeDiscoveryResponse (or QueryIntelligenceSearchResponse for intelligence_search) — see the API Reference for the complete schema.

Pending behavior

If the job is still queued or running when called, returns { "status": "pending" } instead of erroring. Useful for agents that want to call get_context_job_result directly and back off on pending without a separate status check.

Expired

If the job’s TTL has passed (~24 h after completion), returns the underlying 410 from the API:

1
{ "error": "job result expired" }

Resubmit via create_context_job to recompute.

Putting it together

A typical agent loop for intelligence_discover:

1. create_context_job({ kind: "intelligence_discover", input: { query, platforms, window } }) → jobId.
2. If fromCache: true, jump to step 4.
3. get_context_job_status({ jobId }) every 3 s until status: "completed" (or "failed").
4. get_context_job_result({ jobId }) → slim envelope. If you need raw vectors, pass verbose: true.

Most agents handle this entirely autonomously once you cue them with “use kinetk.”