MCP Tools

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

create_context_job

Submit an async job. Pick kind by what you want back:

Rule of thumb: a query → records (the content) or insights (the synthesized analysis).

Input

• records and insights require query (string).
• records also requires limit (integer, 100–10000) — how many records to retrieve. Jobs are billed per record, so there is no default: you choose the spend (1000 is a sensible starting point). A limit above 10000 is rejected with a 400. insights does not accept limit (its scan size is server-fixed).

Filters apply to the records kind. insights takes only query — its time window, scan size and platforms are managed by the service, and the MCP drops any filters/options before submit so the call still succeeds.

Returns

1
{
2
  "jobId": "0190bd6f-1234-7abc-8def-9876543210ab",
3
  "kind": "insights",
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 insights job for luxury watch culture 2026.

get_context_job_status

Cheap poll. Pass the jobId you got from create_context_job.

Returns

1
// running
2
{ "jobId": "...", "kind": "insights", "status": "running",
3
  "submittedAt": 1745859300000, "startedAt": 1745859302100 }
4
5
// completed
6
{ "jobId": "...", "kind": "insights", "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)

The envelope shape depends on kind:

1
// records → the matching content items
2
{
3
  "jobId": "...", "kind": "records", "status": "completed",
4
  "items": [
5
    {
6
      "id": "uuid",
7
      "platform": "TIKTOK",
8
      "title": "...",
9
      "description": "...",
10
      "tags": ["smartwatch", "fitness"],
11
      "similarity": 0.81,
12
      "engagement": { "views": 12500, "likes": 800, "shares": 40, "comments": 60 },
13
      "publishedAt": "2026-05-01T12:00:00.000Z",
14
      "creator": { "followerCount": 120000 }
15
    }
16
  ]
17
}
18
19
// insights → insight signals only (no raw content)
20
{
21
  "jobId": "...", "kind": "insights", "status": "completed",
22
  "query": "...",
23
  "insights": ["..."],
24
  "tagInsights": ["..."],
25
  "narrativeInsights": ["..."]
26
}

Creator identity (handle/display name) and source URLs are never returned; a creator carries only a non-identifying followerCount.

Returns (verbose)

Set verbose: true for the full untouched graph-service payload for the kind — see the API Reference for the complete response shapes.

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), the API’s 410 surfaces as a failed envelope (the API no longer reports the kind at that point):

1
{ "jobId": "...", "kind": "unknown", "status": "failed", "error": "job result expired" }

Resubmit via create_context_job to recompute.

Putting it together

A typical agent loop for insights:

1. create_context_job({ kind: "insights", query: "..." }) → 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. Pass verbose: true for the full untouched payload (more tokens).

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