MCP server

The hosted MCP server lets an AI assistant run and read video analyses. There is nothing to install and no API key: you sign in with your NetraFlow account the first time your client connects.

Connect

claude mcp add --transport http netraflow https://mcp.netraflow.com/mcp

codex mcp add netraflow --url https://mcp.netraflow.com/mcp
codex mcp login netraflow

{
  "mcpServers": {
    "netraflow": {
      "url": "https://mcp.netraflow.com/mcp"
    }
  }
}

Sign-in and workspace

Sign-in is OAuth: a NetraFlow sign-in page, then a page naming the workspace the client will act on, to approve.

An approved connection can do everything the tools below do in that workspace, spending credits included. There are no scopes to choose.

• Which workspace. The first one you joined. check_credits returns its tenant_id and name. You can't switch yet.
• How long it lasts. You approve again every 30 days. Access ends when you leave the workspace.

Tools

Submit spends credits. Write changes something without spending (a follow's matches are charged later). Read changes nothing. The same plan limits apply as on the API. Tools take links only: upload a file of your own in the console or through the Uploads API.

What a tool returns

One block of JSON: the same body as the REST endpoint each tool below links to, with data and meta.request_id, and pagination on lists. Follows have no REST endpoint, so their examples are here.

Errors

A refused call comes back as a tool error, one line of text:

INVALID_QUERY: queries[1] looks like an attempt to change the model's instructions. Ask about the video instead. {"index":1} (request_id: req_8d2kQ0pZ1x7T)

In order: the code, the message, details as JSON when there are any (as on the API, plus follow_id on FOLLOW_EXISTS), a console link when the fix is there (Top up at https://netraflow.com/billing), and the request id to quote to support.

Two other shapes: MCP error -32602: Input validation error: … for an argument that fails its own check (a missing required one, a malformed URL, an empty capabilities, an unknown capability or include value, or more than 50 urls; no request id), and a plain sentence such as NetraFlow is temporarily unavailable. Please try again later.

Job and batch codes are explained on Jobs and Batch. Follow codes:

Jobs

analyze_video

Submit a video for analysis, as POST /v1/jobs does for a link.

Arguments mean what they mean on POST /v1/jobs. With dry_run: true it returns the estimate and no job_id.

Errors: VALIDATION_FAILED, INVALID_URL, INVALID_CAPABILITIES, INVALID_QUERY, TOO_MANY_QUERIES, QUERIES_DISABLED, TOO_MANY_BRANDS, INVALID_SURFACE, MODE_NOT_ALLOWED, JOB_NOT_FOUND (an unknown from_job), INSUFFICIENT_CREDITS, SUBSCRIPTION_PAST_DUE, RATE_LIMITED, CONCURRENT_LIMIT_REACHED, BODY_TOO_LARGE.

check_status

A job without its results: its status, and while it is processing, a progress object.

progress is as on GET /v1/jobs/:id.

Errors: JOB_NOT_FOUND.

get_analysis

A job with its results, as GET /v1/jobs/:id returns it, except that per-frame data is left out unless you ask for it.

Per-frame data can run to megabytes, more than an assistant can take in, so by default it leaves out objects[].appearances[].frames, brands[].appearances[].frame_detections and storyboard.timestamps_ms. Each appearance keeps its times, bounding_box and confidence. include: ["frames"] adds them back; the REST API always returns everything.

A capability that could not run on a job that completed with the rest is listed in meta.failed_capabilities (its capability, code and message), and its result key is absent. A brands or objects run that was cut short completes with meta.brand_detection_degraded or meta.object_detection_degraded set.

What each result holds is on the capability pages. Fetching a storyboard sheet takes an API key: see Frames.

Errors: JOB_NOT_FOUND.

list_analyses

Your jobs, newest first, as GET /v1/jobs lists them.

Each item is a summary, described under List items. Use get_analysis for the rest.

Errors: VALIDATION_FAILED.

cancel_job

Cancel a pending, processing or held job, as POST /v1/jobs/:id/cancel does. A job in a batch can't be cancelled on its own: cancel its batch with cancel_batch.

A job that was running is charged for the work it did, a few seconds after the cancel: read it with get_analysis.

Errors: JOB_NOT_FOUND, JOB_NOT_CANCELLABLE (already ended, or in a batch, whose id the message names).

Batches

create_batch

Submit several links at once, as POST /v1/batch does. Every video gets the same capabilities, questions and objects.

A video listed twice runs once, and jobs has one entry per video.

Errors: VALIDATION_FAILED, INVALID_URL, INVALID_CAPABILITIES, INVALID_QUERY (a question in queries or aggregate.queries, which the message names), TOO_MANY_QUERIES, TOO_MANY_URLS, TOO_MANY_AGGREGATE_QUERIES, QUERIES_DISABLED, BATCH_NOT_ALLOWED, MODE_NOT_ALLOWED, BUDGET_EXCEEDED, INSUFFICIENT_CREDITS, SUBSCRIPTION_PAST_DUE, RATE_LIMITED, CONCURRENT_LIMIT_REACHED, BODY_TOO_LARGE.

get_batch

A batch with every job's status and the answers across the set, as GET /v1/batch/:id returns it.

The status values are under Batch status values.

Errors: BATCH_NOT_FOUND.

list_batches

Your batches, newest first, as GET /v1/batch lists them.

Errors: VALIDATION_FAILED.

cancel_batch

Cancel a processing or paused batch and every job in it that hasn't ended, as POST /v1/batch/:id/cancel does.

Cancelling a batch that is already cancelled succeeds again, with cancelled_jobs: 0.

Errors: BATCH_NOT_FOUND, BATCH_NOT_CANCELLABLE (it already ended completed or failed).

Account

check_credits

The workspace the tools act on, its plan, its credits and its limits, as GET /v1/account returns them. No arguments.

get_usage

Credit totals for a period and the transactions behind them, as GET /v1/usage returns them.

Errors: VALIDATION_FAILED.

Following creators

A follow watches a YouTube channel or TikTok profile: each new upload is checked against your rule for free, and each match is answered and charged. Follows covers rules, channels and the daily digest.

follow_creator

Follow a creator. The rule is judged against each new video's title and description; each match answers question.

How the parts combine is under Rules. Returns the new follow:

{
  "data": {
    "follow_id": "fol_603692fd9dd14f8d",
    "platform": "youtube",
    "creator_handle": "@jawed",
    "creator_name": "jawed",
    "creator_avatar_url": "https://yt3.ggpht.com/…",
    "creator_url": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A",
    "rule": {
      "description": "zoo animals",
      "hashtags": [],
      "mentions": [],
      "keywords": [],
      "requires_disclosure": false
    },
    "rule_summary": "zoo animals",
    "rule_version": 1,
    "question": "Who sponsored the video?",
    "max_duration_minutes": 120,
    "notify": [{ "type": "slack", "target": "https://hooks.slack.com/…a1b2" }],
    "status": "active",
    "paused": false,
    "status_reason": null,
    "consecutive_failures": 0,
    "last_error": null,
    "last_error_at": null,
    "failing_since": null,
    "creator_gone": false,
    "last_polled_at": null,
    "last_matched_at": null,
    "created_at": "2026-10-08T12:00:00.000Z",
    "weekly_cap": 100,
    "stats": { "checked": 0, "matched": 0, "analyzed": 0, "this_week": 0 }
  },
  "meta": { "request_id": "req_xyz789" }
}

Following a creator again with the same rule and question returns FOLLOW_EXISTS. A different rule or question is a second follow: it counts toward your plan's follows, and a video both match is charged once for each.

Errors: VALIDATION_FAILED, INVALID_URL (not a channel or profile that can be found, or an Instagram link, which follows don't support yet), INVALID_QUERY (a description or question written as an instruction to the model rather than about videos), PLAN_REQUIRED, FOLLOW_EXISTS.

list_follows

Every follow in the workspace, and the plan's follow limits. No arguments.

{
  "data": {
    "follows": [
      {
        "follow_id": "fol_603692fd9dd14f8d",
        "platform": "youtube",
        "creator_handle": "@jawed",
        "rule_summary": "zoo animals",
        "status": "active",
        "paused": false,
        "weekly_cap": 100,
        "stats": { "checked": 12, "matched": 2, "analyzed": 2, "this_week": 1 }
      }
    ],
    "limits": { "max_follows": 50, "max_follow_jobs_per_week": 100 }
  },
  "meta": { "request_id": "req_xyz789" }
}

Each item is a whole follow, shortened here. limits.max_follow_jobs_per_week applies to each follow, and equals its weekly_cap.

update_follow

Pause or resume a follow, replace its rule or its question, or replace its channels. Send only what changes.

The rule is replaced, not merged: send any part and the parts you leave out are cleared. A new rule rechecks recent videos, and new matches are offered in the console, never run by themselves. notify is replaced too; leave it out to keep the channels. Returns the updated follow.

Errors: FOLLOW_NOT_FOUND, VALIDATION_FAILED (including a masked notify target, or nothing to change), INVALID_URL (a notify URL that is not allowed), INVALID_QUERY, PLAN_REQUIRED, FOLLOW_EXISTS (the new rule is the one another follow of this creator has), CONFLICT.

unfollow_creator

Delete a follow and its check history. Its analyses are kept. To stop spending but keep the history, pause it instead.

{
  "data": { "follow_id": "fol_603692fd9dd14f8d", "deleted": true },
  "meta": { "request_id": "req_xyz789" }
}

Errors: FOLLOW_NOT_FOUND.

get_follow_activity

The follow's 50 most recent checks, newest first, rejected ones included. A rule edit re-checks a video, so one video can appear twice.

{
  "data": [
    {
      "id": "chk_9f2c71a04b3e5d68",
      "video_id": "jNQXAC9IVRw",
      "video_url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
      "video_title": "Me at the zoo",
      "video_thumbnail_url": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
      "video_published_at": "2005-04-24T03:31:52.000Z",
      "video_duration_seconds": 19,
      "verdict": "matched",
      "reason": "Filmed in front of the elephant enclosure at a zoo.",
      "skip_reason": "backfill",
      "job_id": null,
      "credits_charged": null,
      "rule_version": 1,
      "created_at": "2026-10-08T12:00:05.000Z",
      "job_status": null
    }
  ],
  "meta": { "request_id": "req_xyz789" }
}

Each row is described under The activity row.

Errors: FOLLOW_NOT_FOUND.

The notify item

Each item in notify is one place a finished match is sent:

• slack: a hooks.slack.com incoming-webhook URL. Posts the video, why it matched and the answer.
• webhook: an https:// URL on a public address. Receives the follow.match.completed event, signed and verified like every delivery.
• email: someone already in the workspace.

Up to 5 channels. A match is sent once its answer is written; a failed job sends nothing.

Responses mask Slack and webhook URLs (https://hooks.slack.com/…a1b2), since whoever holds one can post there. A masked target sent back is refused with VALIDATION_FAILED: leave notify out to keep the channels, or send the whole list with full URLs.

The follow object

follow_creator and update_follow return one, and list_follows returns every follow in this shape.

A follow can be paused and need attention at once: status is what to show, paused where it returns once checks work again.

The activity row

get_follow_activity returns one row per check:

A match that wasn't analyzed has a skip_reason. Once it is, its rows carry the job_id instead.

Offered matches are run from the console's Follows page; no tool runs them.

See also: the video MCP server: what you can ask, and how sign-in works.