inseeq MCP — Reference
One endpoint, one key. The key decides who you are and which tools you see — client, operator, or staff.
Overview
inseeq speaks the Model Context Protocol over Streamable HTTP at a single stateless endpoint. There is no configuration beyond the key: the credential you present resolves to a principal, and the server registers only that principal's tools. Two callers hitting the same URL see two different tool lists.
| Principal | Key | Reach |
|---|---|---|
| Client | inseeq_ck_… | One organization, one member. No tool takes an organization argument — the key is the scope. A read_only key runs every read and is refused on writes. |
| Operator | inseeq_op_… | The inseeq operator's identity and the organizations they are assigned to. Every org-facing call names its target org; writes additionally confirm it. |
| Staff | inseeq_op_… | An operator key whose operator carries the platform-admin flag. Same work surface, plus the admin plane. There is no separate admin key. |
One call orients a session
mcp_whoami returns the principal your key resolved to, including every organization you may name and its client_slug. Nothing else needs to be configured or looked up.
Connect
The endpoint is stateless: every request carries its own key, and no session is persisted between calls.
POST https://app.staging.inseeq.com/api/mcp Authorization: Bearer <your key> Content-Type: application/json Accept: application/json, text/event-stream
Both headers are required by the Streamable-HTTP transport. Responses come back as a single JSON body — no SSE stream to hold open.
Claude Code
One command, or the equivalent entry in your project's .mcp.json:
claude mcp add --transport http inseeq https://app.staging.inseeq.com/api/mcp \ --header "Authorization: Bearer $INSEEQ_OPERATOR_KEY"
{
"mcpServers": {
"inseeq": {
"type": "http",
"url": "${INSEEQ_APP_URL:-https://app.staging.inseeq.com}/api/mcp",
"headers": { "Authorization": "Bearer ${INSEEQ_OPERATOR_KEY}" }
}
}
}{
"mcpServers": {
"inseeq": {
"type": "http",
"url": "https://app.staging.inseeq.com/api/mcp",
"headers": { "Authorization": "Bearer ${INSEEQ_CLIENT_KEY}" }
}
}
}Keep the key in the environment, never in the committed file.
Raw JSON-RPC
Any HTTP client works. The three calls below are the whole protocol surface you need.
# 1. initialize — proves the key resolves and the transport is up
curl -s -X POST https://app.staging.inseeq.com/api/mcp \
-H "Authorization: Bearer $INSEEQ_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
# 2. tools/list — exactly the surface your key sees
curl -s -X POST https://app.staging.inseeq.com/api/mcp \
-H "Authorization: Bearer $INSEEQ_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# 3. tools/call — one tool, arguments as documented below
curl -s -X POST https://app.staging.inseeq.com/api/mcp \
-H "Authorization: Bearer $INSEEQ_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"mcp_whoami","arguments":{}}}'Scoping & safety
An operator or staff key can reach several organizations, so every org-facing call must name its target — client_slug or organization_id, from mcp_whoami. Naming an org you are not assigned to is refused, not silently narrowed.
Any client-visible or state-changing write additionally requires confirm_org, set to the target org's client_slug. It is a second, explicit statement of intent: it is what stops one org's work being pushed into another. Client keys never pass it — their org is fixed by the key.
Response envelope
A successful tool call returns its payload as JSON text: parse result.content[0].text. A tool that refuses sets isError: true and puts {"error": "...", "status": 403} in the same place — always check isError before parsing for success.
{ "jsonrpc": "2.0", "id": 3,
"result": { "content": [ { "type": "text", "text": "{\"kind\":\"operator\", ...}" } ] } }
{ "jsonrpc": "2.0", "id": 4,
"result": { "isError": true,
"content": [ { "type": "text", "text": "{\"error\":\"org_not_assigned\",\"status\":403}" } ] } }Authentication and throttling fail earlier, as transport-level JSON-RPC errors with a matching HTTP status.
Error codes
| Error | Status | When |
|---|---|---|
| Unauthorized: missing or invalid Bearer key | 401 | No key, an unknown or revoked key, or a key whose operator has been disabled. JSON-RPC code -32001. |
| organization_required | 400 | An operator/staff call named no org — every org-facing call must pass client_slug or organization_id. |
| org_not_assigned | 403 | You named an org you hold no assignment on. The platform-admin flag lifts this for orgs that exist. |
| confirm_org_mismatch | 403 | A write's confirm_org did not equal the target org's client_slug. The guard against writing into the wrong org. |
| cross_org_forbidden | 403 | A client key named an organization other than the one it is bound to. |
| organization_not_found | 404 | An admin named an organization id or slug that does not exist (or has been deleted). |
| read_only key: this key cannot perform writes | 403 | A read_only client key called a write tool. Every read still works. |
| Rate limit exceeded | 429 | The per-key token bucket is empty. JSON-RPC code -32000; Retry-After says how long to wait. |
Rate limits
One token bucket per key: a burst of 300 requests, refilling at 600 per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the bucket is full again), so a well-behaved agent paces itself and never sees a 429. When the bucket is empty the endpoint answers 429 with JSON-RPC code -32000 and a Retry-After header.
Writes are not idempotent
There is no idempotency key. A write that times out may well have landed — re-read the task or content item and decide, rather than blind-retrying and creating a duplicate.
Bootstrap
Two calls put an agent to work: mcp_whoami for identity and reach, mcp_get_needs_you for what is owed. Then the loop.
1. mcp_whoami — who am I, and which orgs may I name
{ "kind": "operator",
"operator_id": "…", "operator_email": "jane@inseeq.com", "operator_name": "Jane Operator",
"is_platform_admin": false, "linear_linked": true,
"organizations": [ { "id": "…", "name": "PointOne", "client_slug": "pointone" } ],
"operator_org_ids": ["…"] }{ "kind": "client", "organization_id": "…", "organization_name": "PointOne",
"client_slug": "pointone", "permission_class": "read_write" }organizations lists the orgs you are assigned to, each with the client_slug every other tool takes — no second lookup. A client_slug of null is a setup error worth surfacing: writes against that org are impossible until it has one. For a platform admin this list is still just their own assignments; mcp_list_organizations is the enumerator for everything else.
2. mcp_get_needs_you — the session banner
Per-org attention counts plus one urgency-sorted list merged across every org you are assigned to (or a single org, if you name one). It is computed by the same functions that render the operator console, so a banner and the console never disagree.
{ "orgs": [ { "id": "…", "name": "PointOne", "client_slug": "pointone",
"counts": { "ready": 2, "overdue": 12, "needs_reply": 17, "waiting_on_client": 2 } } ],
"items": [ { "org_id": "…", "client_slug": "pointone", "identifier": "CLT-109",
"title": "…", "url": "https://linear.app/…", "project_id": "…",
"due_date": "2026-08-27", "kinds": ["overdue", "needs_reply"] } ],
"total": 24, "has_more": false }counts are exact totals and never clamped by limit; items are. The per-kind tools (mcp_get_ready_to_work, mcp_get_overdue, mcp_get_needs_my_reply, mcp_get_waiting_on_client) drill into one org and one kind.
3. The work loop
mcp_list_projects { client_slug } → pick a project
mcp_get_task / mcp_get_task_context → read one task and its history
mcp_task_focus → declare what you are on (session_id is yours to generate)
mcp_get_task_comments / mcp_post_task_comment
mcp_get_roster { client_slug } → mcp_assign_task
mcp_deliver_for_review { confirm_org: "<slug>" } → hand it to the client
mcp_request_client_input { confirm_org: "<slug>" } → ask for what you are missing
mcp_record_pulse / mcp_record_feedback → session signalsmcp_whoami → confirm the org and permission class mcp_get_waiting_on_you → what inseeq has delivered for your review mcp_get_content / mcp_add_content_comment → read it, leave feedback mcp_accept_delivery | mcp_request_changes | mcp_hand_back
Tool reference
Every entry below is rendered from the exact tools/list JSON schema an MCP client receives — the names, descriptions and parameters here are what the model actually sees. Read the section for the key you hold.
inseeq MCP — Client surface · 36 tools
This is the client surface of the inseeq MCP: everything your organization can do over your own projects, content calendar, and reviews, exposed as tools an AI assistant can call on your behalf.
Your credential. A client key, prefixed inseeq_ck_. It is bound to a single organization and a
single member, so every call is automatically scoped to your org — no tool ever takes an organization
argument, and you can never see or touch another org’s data. A read_write key can create and edit;
a read_only key can run every read but is refused on writes.
How to connect. Connect any MCP-capable client (the Claude desktop app, Claude Code, or your own agent) to the inseeq MCP endpoint at https://app.staging.inseeq.com/api/mcp (the app’s /api/mcp route), authenticating with your key in the Authorization: Bearer <key> header. The key alone decides which tools you see — there is no separate configuration.
Mental model. Think in your own terms: projects hold tasks; your content (articles, LinkedIn posts, events) moves through drafting and review; you leave comments and use the Ask us thread to talk to the inseeq team. When the team delivers something for your review it lands in "waiting on you" — you then accept, request changes, or hand it back.
Worked example — review your content calendar.
mcp_list_content— list the items in your content calendar; note theidof one you want to read.mcp_get_contentwith thatid— read the full item.mcp_add_content_comment— leave feedback on it.mcp_get_waiting_on_you— see what has been delivered for your review, thenmcp_accept_delivery(ormcp_request_changes) on a task.
Identity
mcp_whoami
Returns the calling credential's resolved identity as a ROLE SET: the credential kind (operator | client), and — where they apply — the operator id/email/name, the platform-admin flag, whether a Linear account is linked, and the organizations you may act on with their name and client_slug. A client key returns its single organization and permission class. Call this first; no other lookup is needed to name an org.
No parameters
Content reads
mcp_get_content
Fetch one content item (article, event, or post) in full by id (from list_content).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_get_review_state
A content item's review state (articles and LinkedIn posts, which move through review): current round, status, milestone snapshots, the open review task's assignee, and unresolved comment count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | — |
mcp_list_content
List content (articles, events, and posts), newest-updated first. Optionally filter by content_types, status, or a scheduled/created date range. Bounded; returns total + has_more.
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | No | Filter by status (e.g. draft, in_review, approved, published, scheduled, done). |
| content_types | array<string> | No | Filter by content types, e.g. ["article","linkedin_post"]. |
| from_date | string | No | Inclusive lower bound (YYYY-MM-DD) on scheduled/created date. |
| to_date | string | No | Inclusive upper bound (YYYY-MM-DD). |
| limit | integer | No | Max rows (≤200, default 50). |
| offset | integer | No | — |
Comments, threads & files
mcp_add_content_comment
Add a review comment (or reply) to a content item. Blocked while an item is with Inseeq for review.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| content | string | Yes | The comment text. |
| parent_id | string | No | Reply to this comment id. |
| selection_start | integer | No | — |
| selection_end | integer | No | — |
| selected_text | string | No | — |
mcp_get_ask_us_thread
The project-level “Ask us” discussion thread (its messages, oldest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | string | Yes | The project id from mcp_list_projects. |
mcp_get_task_comments
The client discussion thread on one task (its comments, oldest first).
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier (e.g. "CLT-10") or its id. |
mcp_list_content_comments
List a content item's comments as threads (top-level with nested replies), oldest first, with an author map and unresolved count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_post_ask_us
Post a message into a project’s “Ask us” discussion thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | string | Yes | The project id from mcp_list_projects. |
| body | string | Yes | The message text. |
mcp_post_task_comment
Post a comment into a task’s client discussion thread (visible to your Inseeq team).
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id. |
| body | string | Yes | The comment text. |
mcp_resolve_content_comment
Resolve or unresolve a top-level content comment (replies cannot be resolved).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| comment_id | string | Yes | — |
| resolved | boolean | No | Default true. |
mcp_upload_file
Mint a one-time signed upload URL for a file to attach to a project (direct-to-storage; PUT the bytes to the returned URL, then embed the returned storagePath in a comment/description).
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | string | Yes | The project id from mcp_list_projects. |
| file_name | string | Yes | — |
| file_type | string | Yes | MIME type, e.g. image/png. |
| file_size | integer | Yes | Size in bytes. |
Content writes
mcp_create_content_image
Mint a one-time signed upload URL for an article/post image. The storage path is server-built and org-prefixed (HI-6); PUT the bytes to upload_url, then pass public_url to mcp_set_content_featured_image or into post_images.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The article/post id the image belongs to. |
| mime_type | string | Yes | One of: "image/png", "image/jpeg", "image/gif", "image/webp". |
mcp_create_event
Create a calendar event (podcast, press release, or custom event) on your calendar (status scheduled). custom_event requires custom_event_label. Does not consume an article credit.
| Parameter | Type | Required | Description |
|---|---|---|---|
| event_type | string | Yes | One of: "podcast", "press_release", "custom_event". |
| title | string | Yes | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | No | YYYY-MM-DD. |
mcp_create_linkedin_post
Create a LinkedIn post (status draft). Title derives from the first content line if omitted. post_images is an ordered carousel (max 20). Does not consume an article credit.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | No | YYYY-MM-DD. |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
mcp_request_article
Propose an article for a scheduled month — consumes one article credit (fails if none remain). Created as a draft attributed to you.
| Parameter | Type | Required | Description |
|---|---|---|---|
| title | string | Yes | The article title. |
| scheduled_publish_date | string | Yes | The month this credit is drawn from is the month of this date (YYYY-MM-DD). |
| description | string | No | The brief/description (becomes the draft body until an admin writes it). |
| category_id | string | No | — |
| meta_description | string | No | — |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
mcp_set_content_featured_image
Set featured-image fields only (url, alt_text, title, caption, description). Cannot touch the body.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| featured_image_url | string | No | — |
| featured_image_alt_text | string | No | — |
| featured_image_title | string | No | — |
| featured_image_caption | string | No | — |
| featured_image_description | string | No | — |
mcp_update_content_metadata
Update editorial metadata only (title, excerpt, description, language, scheduled date, target_keyword, outline, cluster_topic). Cannot touch body/SEO/image. A title change snapshots a version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| title | string | No | — |
| excerpt | string | No | — |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| scheduled_publish_date | string | null | No | ISO date; null clears. |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
mcp_update_content_seo
Update SEO fields only: meta_description, focus_keyphrase, seo_title, slug (→ wordpress_slug). No snapshot.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| meta_description | string | No | — |
| focus_keyphrase | string | No | — |
| seo_title | string | No | — |
| slug | string | No | Written to wordpress_slug. |
mcp_update_content_status
Change a content item’s status (subject to the same client rules as the portal). Handles articles, posts and events.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| status | string | Yes | Target status (article: draft|generating|in_review|approved|published; event: scheduled|done). |
| scheduled_publish_date | string | No | Optional date to set alongside the transition. |
mcp_update_event
Update a calendar event (title, content, custom_event_label, scheduled date).
| Parameter | Type | Required | Description |
|---|---|---|---|
| event_id | string | Yes | — |
| title | string | No | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | null | No | YYYY-MM-DD, or null to clear. |
mcp_update_linkedin_post
Update a LinkedIn post. Content/title changes snapshot a version; title auto-derives from content when a new title is not given. post_images replaces the whole array.
| Parameter | Type | Required | Description |
|---|---|---|---|
| post_id | string | Yes | — |
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | null | No | YYYY-MM-DD, or null to clear. |
mcp_write_article_body
Replace an article body with full markdown. Snapshots the prior version, re-parses intro/sections/sources, recomputes word_count, bumps version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| content | string | Yes | Full markdown body (entire article; partial not supported). |
Tasks & projects
mcp_assign_task
Set (or clear) a task's assignee. assignee: {kind:'operator',id} | {kind:'member',id} | null to clear. Both ids come from mcp_get_roster — the operator id, not a Linear id. An operator whose roster entry has assignable:false cannot take a task (409 operator_not_linear_linked).
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id. |
| assignee | object | null | No | Assignee: {kind:"operator",id} or {kind:"member",id} (id from mcp_get_roster), or null to clear. |
mcp_create_task
Create a task in one of your projects (created as you; carries the “added by you” provenance).
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | string | Yes | The project id from mcp_list_projects. |
| title | string | Yes | — |
| description | string | No | — |
| stateType | string | No | Task state. Cancel/delete are intentionally not available to clients. One of: "backlog", "unstarted", "started", "completed". |
| milestoneId | string | No | — |
| dueDate | string | No | YYYY-MM-DD. |
| priority | integer | No | Priority 0–4 (0 = none). |
| assignee | object | null | No | Assignee: {kind:"operator",id} or {kind:"member",id} (id from mcp_get_roster), or null to clear. |
mcp_edit_task
Edit a task: title, status, description, due date, milestone, priority or assignee. Clients cannot cancel or delete tasks.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id. |
| title | string | No | — |
| stateType | string | No | Task state. Cancel/delete are intentionally not available to clients. One of: "backlog", "unstarted", "started", "completed". |
| description | string | No | — |
| dueDate | string | null | No | YYYY-MM-DD, or null to clear. |
| milestoneId | string | null | No | Milestone id, or null to remove. |
| priority | integer | No | — |
| assignee | object | null | No | Assignee: {kind:"operator",id} or {kind:"member",id} (id from mcp_get_roster), or null to clear. |
mcp_get_project
One project and its tasks (the board + side-peek payload).
| Parameter | Type | Required | Description |
|---|---|---|---|
| project_id | string | Yes | The project id from mcp_list_projects. |
mcp_get_roster
Who a task can be assigned to in your organization: your inseeq operators and your own org members. Use an entry’s id as mcp_assign_task’s assignee id. An operator with assignable:false is not yet linked to a Linear account and cannot hold a task.
No parameters
mcp_get_task
One task on your board: title, state, description, labels, due, priority, assignee.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier (e.g. "CLT-10") or its id. |
mcp_list_projects
Your organization’s projects, each with its summary (health, dates, waiting counts, next milestone).
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Max projects to return (default 50). |
mcp_set_task_status
Set a task's workflow state (backlog | unstarted | started | completed). Cancel/delete are not available to clients.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id. |
| status | string | Yes | Task state. Cancel/delete are intentionally not available to clients. One of: "backlog", "unstarted", "started", "completed". |
Obligations
mcp_get_waiting_on_you
The tasks across all your projects that are waiting on you right now (delivered for your review, or asking for your input), newest first. Optionally filter to one lane.
| Parameter | Type | Required | Description |
|---|---|---|---|
| lane | string | No | Filter to one lane: ready_for_review (delivered for your review) or needs_input (asking for your input). One of: "ready_for_review", "needs_input". |
Handoff
mcp_accept_delivery
Accept delivered work — marks the task complete. Irreversible, so `confirm` must be true.
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id (must be delivered for your review). |
| confirm | boolean | Yes | Must be true — acceptance completes the task and cannot be undone. |
mcp_hand_back
Hand a task that was asking for your input back to Inseeq, optionally with a comment (lane action).
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id (must be asking for your input). |
| comment | string | No | Optional note to include. |
mcp_request_changes
Send delivered work back for changes with a required comment (lane action; the task returns to In progress).
| Parameter | Type | Required | Description |
|---|---|---|---|
| task | string | Yes | Task identifier or id (must be delivered for your review). |
| comment | string | Yes | What needs to change (required). |
Org relationship
mcp_get_credits
Your article-credit balance for a month (allowance, planned, remaining).
| Parameter | Type | Required | Description |
|---|---|---|---|
| month | string | No | YYYY-MM; defaults to the current month. |
inseeq MCP — Operator surface · 53 tools
This is the operator surface of the inseeq MCP: everything an inseeq operator can do across the client organizations they are assigned to.
Your credential. An operator key, prefixed inseeq_op_. It resolves to your operator identity and
the set of organizations you are assigned to. Every org-facing call must name its target org
(via client_slug or organization_id), and you can only ever name an org you are assigned to. Any
client-visible or state-changing write additionally requires a confirm_org argument equal to that
org’s slug — the guard against pushing one org’s work into another.
How to connect. Connect any MCP-capable client (the Claude desktop app, Claude Code, or your own agent) to the inseeq MCP endpoint at https://app.staging.inseeq.com/api/mcp (the app’s /api/mcp route), authenticating with your key in the Authorization: Bearer <key> header. The key alone decides which tools you see — there is no separate configuration.
Mental model. Across your assigned orgs you run the same projects / tasks / content surface a client sees, plus the operator work loop: triage what is ready to work, overdue, or waiting on the client; do the work; deliver for review or request client input; and record session signals (focus, pulse, feedback) as you go.
Worked example — pick up and deliver work.
mcp_get_needs_you— the session banner: per-org counts and the urgency-sorted list of everything owed across your assigned orgs (mcp_get_ready_to_workand friends drill into one org and one kind).mcp_get_task— open one and read its detail.mcp_task_focus— mark it as what you are working on.- Do the work (e.g.
mcp_write_article_body,mcp_update_content_metadata). mcp_deliver_for_reviewwithconfirm_orgset to the org’s slug — hand it to the client.
Identity
mcp_whoami
Returns the calling credential's resolved identity as a ROLE SET: the credential kind (operator | client), and — where they apply — the operator id/email/name, the platform-admin flag, whether a Linear account is linked, and the organizations you may act on with their name and client_slug. A client key returns its single organization and permission class. Call this first; no other lookup is needed to name an org.
No parameters
Content reads
mcp_get_content
Fetch one content item (article, event, or post) in full by id (from list_content).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_get_review_state
A content item's review state (articles and LinkedIn posts, which move through review): current round, status, milestone snapshots, the open review task's assignee, and unresolved comment count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | — |
mcp_list_content
List content (articles, events, and posts), newest-updated first. Optionally filter by content_types, status, or a scheduled/created date range. Bounded; returns total + has_more.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| status | string | No | Filter by status (e.g. draft, in_review, approved, published, scheduled, done). |
| content_types | array<string> | No | Filter by content types, e.g. ["article","linkedin_post"]. |
| from_date | string | No | Inclusive lower bound (YYYY-MM-DD) on scheduled/created date. |
| to_date | string | No | Inclusive upper bound (YYYY-MM-DD). |
| limit | integer | No | Max rows (≤200, default 50). |
| offset | integer | No | — |
Comments, threads & files
mcp_add_content_comment
Add a comment (or reply) on a content item, anchored to the current review round. Author is the operator (HI-2).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| content | string | Yes | — |
| parent_id | string | No | — |
| selection_start | integer | No | — |
| selection_end | integer | No | — |
| selected_text | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_get_ask_us_thread
Read the project-level "Ask us" discussion thread (its messages, oldest first). thread_exists:false means no thread yet (posting opens one).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
mcp_get_task_comments
Read the client-visible "💬 Client discussion" thread on a task — the comments the CLIENT can see, with who wrote each. thread_exists:false means no thread yet (posting opens one).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_list_content_comments
List a content item's comments as threads (top-level with nested replies), oldest first, with an author map and unresolved count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_post_ask_us
Post a message into a project's "Ask us" discussion thread (visible to the client). Opens the thread if none exists. Post only wording the operator approved verbatim.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| project_id | string | Yes | The project uuid. |
| body | string | Yes | The exact approved message, markdown. |
mcp_post_task_comment
Post a comment the CLIENT will see in the task's "💬 Client discussion" thread (and email subscribed members). Opens the thread if none exists. Post only wording the operator approved verbatim.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| body | string | Yes | The exact approved message, markdown. |
mcp_resolve_content_comment
Resolve or unresolve a top-level content comment (replies cannot be resolved).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| comment_id | string | Yes | — |
| resolved | boolean | No | Default true. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_upload_file
Mint a one-time signed upload URL for a file to attach to a project (direct-to-storage; PUT the bytes to the returned URL, then embed the returned storagePath in a comment/description).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
| file_name | string | Yes | — |
| file_type | string | Yes | MIME type, e.g. image/png. |
| file_size | integer | Yes | Size in bytes. |
Content writes
mcp_create_article
Create a long-form article draft directly (operator, ungated — no credit is consumed, unlike the client mcp_request_article). Optional markdown content is parsed into intro/sections/sources and word_count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| title | string | Yes | — |
| content | string | No | Optional full markdown body; parsed on insert. |
| description | string | No | — |
| excerpt | string | No | — |
| meta_description | string | No | — |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
| category_id | string | No | — |
| scheduled_publish_date | string | null | No | — |
| language | string | No | — |
| language_code | string | No | — |
| status | string | No | Initial status (default draft). One of: "draft", "ready_to_write", "writing", "generating", "in_review", "approved", "published". |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_create_content_image
Mint a one-time signed upload URL for an article/post image. The storage path is server-built and org-prefixed (HI-6); PUT the bytes to upload_url, then pass public_url to mcp_set_content_featured_image or into post_images.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The article/post id the image belongs to. |
| mime_type | string | Yes | One of: "image/png", "image/jpeg", "image/gif", "image/webp". |
mcp_create_event
Create a calendar event (status scheduled). custom_event requires custom_event_label; the others must omit it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| event_type | string | Yes | One of: "podcast", "press_release", "custom_event". |
| title | string | Yes | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_create_linkedin_post
Create a LinkedIn post (status draft). Title derives from the first content line if omitted. post_images is an ordered carousel (max 20).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | No | — |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_publish_article
Publish an approved article to the org's active CMS platform (WordPress/Webflow/Contentful/emdash/Shopify/Framer) via the same publishers the app publish route uses. LinkedIn posts and events cannot be published this way.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| status | string | No | WordPress post status only. One of: "publish", "draft", "pending". |
| categories | array<number> | No | WordPress category IDs. |
| tags | array<number> | No | WordPress tag IDs. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_send_article_for_rereview
Open the next review round on an in_review article: snapshots a milestone version, increments review_round, and hands the open review task back to the client. Status stays in_review.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_set_content_featured_image
Set featured-image fields only (url, alt_text, title, caption, description). Cannot touch the body.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| featured_image_url | string | No | — |
| featured_image_alt_text | string | No | — |
| featured_image_title | string | No | — |
| featured_image_caption | string | No | — |
| featured_image_description | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_metadata
Update editorial metadata only (title, excerpt, description, language, scheduled date, target_keyword, outline, cluster_topic). Cannot touch body/SEO/image. A title change snapshots a version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| title | string | No | — |
| excerpt | string | No | — |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| scheduled_publish_date | string | null | No | ISO date; null clears. |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_seo
Update SEO fields only: meta_description, focus_keyphrase, seo_title, slug (→ wordpress_slug). No snapshot.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| meta_description | string | No | — |
| focus_keyphrase | string | No | — |
| seo_title | string | No | — |
| slug | string | No | Written to wordpress_slug. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_status
Change a content item's status. Articles and LinkedIn posts move through draft, ready_to_write, writing, generating, in_review, approved, published (stamping workflow timestamps, syncing the review task, sending review/approval emails); events toggle between scheduled and done.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| status | string | Yes | Target status. Article/post: draft|ready_to_write|writing|generating|in_review|approved|published. Event: scheduled|done. |
| scheduled_publish_date | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_event
Update a calendar event (title, content, custom_event_label, scheduled date).
| Parameter | Type | Required | Description |
|---|---|---|---|
| event_id | string | Yes | — |
| title | string | No | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | null | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_linkedin_post
Update a LinkedIn post. Content/title changes snapshot a version; title auto-derives from content when a new title is not given. post_images replaces the whole array.
| Parameter | Type | Required | Description |
|---|---|---|---|
| post_id | string | Yes | — |
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | null | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_write_article_body
Replace an article body with full markdown. Snapshots the prior version, re-parses intro/sections/sources, recomputes word_count, bumps version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| content | string | Yes | Full markdown body (entire article; partial not supported). |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
Tasks & projects
mcp_assign_task
Set (or clear) a task's assignee. assignee: {kind:'operator',operatorId} | {kind:'member',userId} | null to clear both sides. Ids come from mcp_get_roster; an operator with assignable:false has no Linear account linked and is refused with 409 operator_not_linear_linked.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| assignee | object | null | Yes | — |
mcp_cancel_task
Cancel a task (moves it to the canceled state). Operators may cancel; this is the only cancel path.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_create_task
Create a task in a project. project_id is the project uuid.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| project_id | string | Yes | The project uuid. |
| title | string | Yes | — |
| description | string | No | — |
| status | string | No | Initial state (default unstarted). One of: "backlog", "unstarted", "started", "completed". |
| milestone_id | string | No | Milestone uuid. |
| due_date | string | No | YYYY-MM-DD. |
| priority | integer | No | — |
| assignee | object | null | No | — |
mcp_edit_task
Edit a task: any of title, description, status, due_date (null clears), milestone_id (null removes), priority (0-4), assignee. No project change; no cancel (use mcp_cancel_task).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| title | string | No | — |
| description | string | No | — |
| status | string | No | One of: "backlog", "unstarted", "started", "completed". |
| due_date | string | null | No | YYYY-MM-DD, or null to clear. |
| milestone_id | string | null | No | Milestone uuid, or null to remove. |
| priority | integer | No | — |
| assignee | object | null | No | — |
mcp_get_project
One project and its tasks (the board detail). project_id is the project uuid.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
mcp_get_roster
Who a task can be assigned to in one client org: the org’s inseeq operators (id, name, email, Linear link) and the org’s own members. Use an entry’s id as mcp_assign_task’s assignee id. An operator with assignable:false is not linked to a Linear account and cannot hold a task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
mcp_get_task
One task: title, state, description, labels, due, priority, assignee, thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_list_projects
The org's active projects (completed/canceled excluded), each with its open-proposal count and its count of tasks unblocked-and-ready to work. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
mcp_set_task_status
Set a task's workflow state. status is one of backlog | unstarted | started | completed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| status | string | Yes | One of: "backlog", "unstarted", "started", "completed". |
Obligations
mcp_get_due_soon
Open tasks due within N days (default 7), soonest first. Bounded, with the true total.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
| within_days | integer | No | Horizon in days (default 7). |
mcp_get_needs_my_reply
Open tasks whose latest client-thread comment was written by the CLIENT — the operator owes a reply.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_needs_you
The session banner: what is owed across the organizations you are assigned to — per-org counts (ready, overdue, needs_reply, waiting_on_client) plus the merged, urgency-sorted list of the tasks behind them, each tagged with the kinds it surfaced under. Name an org (client_slug or organization_id) to scope it to one; with no org named it covers every assigned org. Counts are exact totals; items are bounded by limit. This is the same computation the operator console home renders.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| limit | integer | No | Maximum items returned (default 50). Counts are unaffected. |
mcp_get_overdue
Open tasks whose due date has passed, oldest miss first. Bounded, with the true total.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_ready_to_work
Tasks ready to work: distinct open tasks with an unconsumed readiness signal that surfaces (not client-waiting unless an approved unblock or a new client reply). Read-only — never consumes rows.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_waiting_on_client
Open tasks the CLIENT is holding (the needs-input / ready-for-review lane, or the vestigial "With Client" status). Each row carries lane (needs_input | ready_for_review), since (when the client got it — the ask or the delivery stamp) and ask (the latest operator comment in the client thread — the ask as the client sees it); null when unknown.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
Handoff
mcp_deliver_for_review
Deliver a task to the client for review (moves it into their "ready for review" lane). Optional comment.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| comment | string | No | Optional note posted to the client thread with the delivery. |
mcp_request_client_input
Ask the client for input on a task (moves it into their "needs your input" lane). Comment required.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| comment | string | Yes | The question/ask posted to the client thread. Required. |
Operator signals
mcp_get_task_context
A task's context pack: the task, every recorded operator decision, every approved comms attachment, and readiness evidence — compact chronological markdown.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_record_feedback
Record in-the-moment operator feedback about the system (/note): free text, no rating. Store the words verbatim. context_line is a one-sentence description of what was happening. issue_id defaults to the session's open focus task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| session_id | string | Yes | This session UUID. |
| body | string | Yes | The operator's feedback, verbatim. |
| context_line | string | No | One sentence: what was happening when they said it. |
| issue_id | string | No | Identifier or uuid; omit to use the session's open focus span. |
mcp_record_pulse
Record the operator's 1-3 rating of how the SYSTEM is going (never a rating of the operator). 1 = fought it, 2 = fine, 3 = worked well. issue_id defaults to the session's open focus task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| session_id | string | Yes | This session UUID. |
| rating | integer | Yes | 1 = fought it · 2 = fine · 3 = worked well |
| source | string | Yes | 'end' = the /end sign-off; 'random' = the daily mid-session ask One of: "end", "random". |
| note | string | No | The operator's words, verbatim. |
| issue_id | string | No | Identifier or uuid; omit to use the session's open focus span. |
mcp_task_focus
Start, switch, or clear this session's task focus. 'start'/'switch' close any open span for this session, open a new one on issue_id, and return the task's context pack. 'clear' closes the open span. The operator identity comes from the key.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| action | string | Yes | One of: "start", "switch", "clear". |
| session_id | string | Yes | This session UUID (a correlator, not identity). |
| issue_id | string | No | Required for 'start'/'switch': identifier or uuid. |
| model | string | No | Self-reported model, recorded on the span. |
| effort | string | No | Self-reported reasoning effort, recorded on the span. |
| project_id | string | No | Optional project uuid active when focus started. |
mcp_trigger_comms_check
Queue the comms router for this client ('check comms'): emits comms/route.requested and returns immediately. It does NOT block on the comms sync. Re-fetch the queue shortly after for results.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
Org relationship
mcp_get_credits
Article-credit balance for one organization in a month (default current UTC month). Contract allowance minus articles scheduled that month.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| month | string | No | — |
mcp_get_organization
Full detail for one organization named by organization_id or client_slug: brand, contract, review settings, the operator roster, and project/article counts.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
mcp_invite_user_to_org
Invite a user (by email) to an organization. Creates a pending organization_invitations row and sends the invite email best-effort. Requires organization_id + confirm_org (HI-3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| string | Yes | — | |
| first_name | string | No | — |
| last_name | string | No | — |
mcp_list_organizations
List organizations you may act on: id, name, client_slug, whether it carries a contract, and created_at. An operator sees only the orgs it is assigned to; a platform admin sees every active org. Bounded and paginated (HI-5).
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | — |
| offset | integer | No | — |
mcp_publish_linear_project
Publish a Linear project to the client's portal with zero admin involvement. Ensures the org has a linked Linear initiative (adopts one whose name matches the org, else creates it), adds the project to it, tags it with the client's project label, defaults an empty lead to the creator, and syncs the portal mirror inline — the project is live on /projects when this returns. Idempotent: re-running on a published project is a no-op success. `client_label_set: false` means the publish succeeded but the label did not — flag it, do not retry. Requires organization_id + confirm_org (HI-3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| linear_project_id | string | No | The Linear project uuid to publish. Omit to only ensure the initiative exists. |
mcp_set_contract
Set an organization's contract (organizations.contract jsonb) — this drives the article credit allowance. articles_per_month is required; other fields merge over the existing contract. Requires organization_id + confirm_org (HI-3). Returns the new credit balance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| articles_per_month | integer | Yes | — |
| duration_months | integer | No | — |
| start_date | string | No | — |
| auto_renew | boolean | No | — |
inseeq MCP — Staff surface (operator + admin) · 58 tools
This is the staff surface of the inseeq MCP: the operator work surface plus the admin plane. It
is the single evergreen doc for an inseeq power user — everything an operator can do, plus platform-wide
management. There is no separate admin key: admin is the is_platform_admin flag on your operator key.
Your credential. An operator key (inseeq_op_) whose operator row carries is_platform_admin. The
work + org-relationship tools are scoped to your assigned orgs exactly as for an operator; the admin
plane additionally lets you reach any non-deleted org (each admin write still names and confirms its
target org). A pure admin — the flag with no assignments — gets the admin plane only, and no execution
surface.
How to connect. Connect any MCP-capable client (the Claude desktop app, Claude Code, or your own agent) to the inseeq MCP endpoint at https://app.staging.inseeq.com/api/mcp (the app’s /api/mcp route), authenticating with your key in the Authorization: Bearer <key> header. The key alone decides which tools you see — there is no separate configuration.
Mental model. Everything in the operator surface, plus the admin plane: provision organizations, assign and revoke operators, and read cross-org overviews and operator dashboards. Use the operator loop for delivery work; use the admin plane for account and fleet management.
Worked example — provision a client, then work it.
mcp_create_organization— create the client org.mcp_assign_operator— assign an operator (possibly yourself) to it.mcp_get_org_overview— read its project/task/content/credit rollup.- From there the full operator loop applies (
mcp_get_ready_to_work→ … →mcp_deliver_for_review).
Identity
mcp_whoami
Returns the calling credential's resolved identity as a ROLE SET: the credential kind (operator | client), and — where they apply — the operator id/email/name, the platform-admin flag, whether a Linear account is linked, and the organizations you may act on with their name and client_slug. A client key returns its single organization and permission class. Call this first; no other lookup is needed to name an org.
No parameters
Content reads
mcp_get_content
Fetch one content item (article, event, or post) in full by id (from list_content).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_get_review_state
A content item's review state (articles and LinkedIn posts, which move through review): current round, status, milestone snapshots, the open review task's assignee, and unresolved comment count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | — |
mcp_list_content
List content (articles, events, and posts), newest-updated first. Optionally filter by content_types, status, or a scheduled/created date range. Bounded; returns total + has_more.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| status | string | No | Filter by status (e.g. draft, in_review, approved, published, scheduled, done). |
| content_types | array<string> | No | Filter by content types, e.g. ["article","linkedin_post"]. |
| from_date | string | No | Inclusive lower bound (YYYY-MM-DD) on scheduled/created date. |
| to_date | string | No | Inclusive upper bound (YYYY-MM-DD). |
| limit | integer | No | Max rows (≤200, default 50). |
| offset | integer | No | — |
Comments, threads & files
mcp_add_content_comment
Add a comment (or reply) on a content item, anchored to the current review round. Author is the operator (HI-2).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| content | string | Yes | — |
| parent_id | string | No | — |
| selection_start | integer | No | — |
| selection_end | integer | No | — |
| selected_text | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_get_ask_us_thread
Read the project-level "Ask us" discussion thread (its messages, oldest first). thread_exists:false means no thread yet (posting opens one).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
mcp_get_task_comments
Read the client-visible "💬 Client discussion" thread on a task — the comments the CLIENT can see, with who wrote each. thread_exists:false means no thread yet (posting opens one).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_list_content_comments
List a content item's comments as threads (top-level with nested replies), oldest first, with an author map and unresolved count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
mcp_post_ask_us
Post a message into a project's "Ask us" discussion thread (visible to the client). Opens the thread if none exists. Post only wording the operator approved verbatim.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| project_id | string | Yes | The project uuid. |
| body | string | Yes | The exact approved message, markdown. |
mcp_post_task_comment
Post a comment the CLIENT will see in the task's "💬 Client discussion" thread (and email subscribed members). Opens the thread if none exists. Post only wording the operator approved verbatim.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| body | string | Yes | The exact approved message, markdown. |
mcp_resolve_content_comment
Resolve or unresolve a top-level content comment (replies cannot be resolved).
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| comment_id | string | Yes | — |
| resolved | boolean | No | Default true. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_upload_file
Mint a one-time signed upload URL for a file to attach to a project (direct-to-storage; PUT the bytes to the returned URL, then embed the returned storagePath in a comment/description).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
| file_name | string | Yes | — |
| file_type | string | Yes | MIME type, e.g. image/png. |
| file_size | integer | Yes | Size in bytes. |
Content writes
mcp_create_article
Create a long-form article draft directly (operator, ungated — no credit is consumed, unlike the client mcp_request_article). Optional markdown content is parsed into intro/sections/sources and word_count.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| title | string | Yes | — |
| content | string | No | Optional full markdown body; parsed on insert. |
| description | string | No | — |
| excerpt | string | No | — |
| meta_description | string | No | — |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
| category_id | string | No | — |
| scheduled_publish_date | string | null | No | — |
| language | string | No | — |
| language_code | string | No | — |
| status | string | No | Initial status (default draft). One of: "draft", "ready_to_write", "writing", "generating", "in_review", "approved", "published". |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_create_content_image
Mint a one-time signed upload URL for an article/post image. The storage path is server-built and org-prefixed (HI-6); PUT the bytes to upload_url, then pass public_url to mcp_set_content_featured_image or into post_images.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The article/post id the image belongs to. |
| mime_type | string | Yes | One of: "image/png", "image/jpeg", "image/gif", "image/webp". |
mcp_create_event
Create a calendar event (status scheduled). custom_event requires custom_event_label; the others must omit it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| event_type | string | Yes | One of: "podcast", "press_release", "custom_event". |
| title | string | Yes | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_create_linkedin_post
Create a LinkedIn post (status draft). Title derives from the first content line if omitted. post_images is an ordered carousel (max 20).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | Client slug of the target org. Operator/admin must name the org (this or organization_id). |
| organization_id | string | No | Target org id (alternative to client_slug). |
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | No | — |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_publish_article
Publish an approved article to the org's active CMS platform (WordPress/Webflow/Contentful/emdash/Shopify/Framer) via the same publishers the app publish route uses. LinkedIn posts and events cannot be published this way.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| status | string | No | WordPress post status only. One of: "publish", "draft", "pending". |
| categories | array<number> | No | WordPress category IDs. |
| tags | array<number> | No | WordPress tag IDs. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_send_article_for_rereview
Open the next review round on an in_review article: snapshots a milestone version, increments review_round, and hands the open review task back to the client. Status stays in_review.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_set_content_featured_image
Set featured-image fields only (url, alt_text, title, caption, description). Cannot touch the body.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| featured_image_url | string | No | — |
| featured_image_alt_text | string | No | — |
| featured_image_title | string | No | — |
| featured_image_caption | string | No | — |
| featured_image_description | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_metadata
Update editorial metadata only (title, excerpt, description, language, scheduled date, target_keyword, outline, cluster_topic). Cannot touch body/SEO/image. A title change snapshots a version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| title | string | No | — |
| excerpt | string | No | — |
| description | string | No | — |
| language | string | No | — |
| language_code | string | No | — |
| scheduled_publish_date | string | null | No | ISO date; null clears. |
| target_keyword | string | No | — |
| outline | string | No | — |
| cluster_topic | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_seo
Update SEO fields only: meta_description, focus_keyphrase, seo_title, slug (→ wordpress_slug). No snapshot.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| meta_description | string | No | — |
| focus_keyphrase | string | No | — |
| seo_title | string | No | — |
| slug | string | No | Written to wordpress_slug. |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_content_status
Change a content item's status. Articles and LinkedIn posts move through draft, ready_to_write, writing, generating, in_review, approved, published (stamping workflow timestamps, syncing the review task, sending review/approval emails); events toggle between scheduled and done.
| Parameter | Type | Required | Description |
|---|---|---|---|
| content_id | string | Yes | The content item id (from list_content). |
| status | string | Yes | Target status. Article/post: draft|ready_to_write|writing|generating|in_review|approved|published. Event: scheduled|done. |
| scheduled_publish_date | string | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_event
Update a calendar event (title, content, custom_event_label, scheduled date).
| Parameter | Type | Required | Description |
|---|---|---|---|
| event_id | string | Yes | — |
| title | string | No | — |
| content | string | No | — |
| custom_event_label | string | No | — |
| scheduled_publish_date | string | null | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_update_linkedin_post
Update a LinkedIn post. Content/title changes snapshot a version; title auto-derives from content when a new title is not given. post_images replaces the whole array.
| Parameter | Type | Required | Description |
|---|---|---|---|
| post_id | string | Yes | — |
| content | string | No | — |
| title | string | No | — |
| post_images | array<object> | No | — |
| scheduled_publish_date | string | null | No | — |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
mcp_write_article_body
Replace an article body with full markdown. Snapshots the prior version, re-parses intro/sections/sources, recomputes word_count, bumps version.
| Parameter | Type | Required | Description |
|---|---|---|---|
| article_id | string | Yes | — |
| content | string | Yes | Full markdown body (entire article; partial not supported). |
| confirm_org | string | Yes | HI-3 cross-org write guard: must equal the target org's client_slug. |
Tasks & projects
mcp_assign_task
Set (or clear) a task's assignee. assignee: {kind:'operator',operatorId} | {kind:'member',userId} | null to clear both sides. Ids come from mcp_get_roster; an operator with assignable:false has no Linear account linked and is refused with 409 operator_not_linear_linked.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| assignee | object | null | Yes | — |
mcp_cancel_task
Cancel a task (moves it to the canceled state). Operators may cancel; this is the only cancel path.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_create_task
Create a task in a project. project_id is the project uuid.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| project_id | string | Yes | The project uuid. |
| title | string | Yes | — |
| description | string | No | — |
| status | string | No | Initial state (default unstarted). One of: "backlog", "unstarted", "started", "completed". |
| milestone_id | string | No | Milestone uuid. |
| due_date | string | No | YYYY-MM-DD. |
| priority | integer | No | — |
| assignee | object | null | No | — |
mcp_edit_task
Edit a task: any of title, description, status, due_date (null clears), milestone_id (null removes), priority (0-4), assignee. No project change; no cancel (use mcp_cancel_task).
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| title | string | No | — |
| description | string | No | — |
| status | string | No | One of: "backlog", "unstarted", "started", "completed". |
| due_date | string | null | No | YYYY-MM-DD, or null to clear. |
| milestone_id | string | null | No | Milestone uuid, or null to remove. |
| priority | integer | No | — |
| assignee | object | null | No | — |
mcp_get_project
One project and its tasks (the board detail). project_id is the project uuid.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| project_id | string | Yes | The project uuid. |
mcp_get_roster
Who a task can be assigned to in one client org: the org’s inseeq operators (id, name, email, Linear link) and the org’s own members. Use an entry’s id as mcp_assign_task’s assignee id. An operator with assignable:false is not linked to a Linear account and cannot hold a task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
mcp_get_task
One task: title, state, description, labels, due, priority, assignee, thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_list_projects
The org's active projects (completed/canceled excluded), each with its open-proposal count and its count of tasks unblocked-and-ready to work. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
mcp_set_task_status
Set a task's workflow state. status is one of backlog | unstarted | started | completed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| status | string | Yes | One of: "backlog", "unstarted", "started", "completed". |
Obligations
mcp_get_due_soon
Open tasks due within N days (default 7), soonest first. Bounded, with the true total.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
| within_days | integer | No | Horizon in days (default 7). |
mcp_get_needs_my_reply
Open tasks whose latest client-thread comment was written by the CLIENT — the operator owes a reply.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_needs_you
The session banner: what is owed across the organizations you are assigned to — per-org counts (ready, overdue, needs_reply, waiting_on_client) plus the merged, urgency-sorted list of the tasks behind them, each tagged with the kinds it surfaced under. Name an org (client_slug or organization_id) to scope it to one; with no org named it covers every assigned org. Counts are exact totals; items are bounded by limit. This is the same computation the operator console home renders.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| limit | integer | No | Maximum items returned (default 50). Counts are unaffected. |
mcp_get_overdue
Open tasks whose due date has passed, oldest miss first. Bounded, with the true total.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_ready_to_work
Tasks ready to work: distinct open tasks with an unconsumed readiness signal that surfaces (not client-waiting unless an approved unblock or a new client reply). Read-only — never consumes rows.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
mcp_get_waiting_on_client
Open tasks the CLIENT is holding (the needs-input / ready-for-review lane, or the vestigial "With Client" status). Each row carries lane (needs_input | ready_for_review), since (when the client got it — the ask or the delivery stamp) and ask (the latest operator comment in the client thread — the ask as the client sees it); null when unknown.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| limit | integer | No | Max rows (default 50, hard max 100). The response carries the true total. |
Handoff
mcp_deliver_for_review
Deliver a task to the client for review (moves it into their "ready for review" lane). Optional comment.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| comment | string | No | Optional note posted to the client thread with the delivery. |
mcp_request_client_input
Ask the client for input on a task (moves it into their "needs your input" lane). Comment required.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
| comment | string | Yes | The question/ask posted to the client thread. Required. |
Operator signals
mcp_get_task_context
A task's context pack: the task, every recorded operator decision, every approved comms attachment, and readiness evidence — compact chronological markdown.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| issue_id | string | Yes | The task: its identifier ('CLT-10') or its uuid. Scoped to the target org. |
mcp_record_feedback
Record in-the-moment operator feedback about the system (/note): free text, no rating. Store the words verbatim. context_line is a one-sentence description of what was happening. issue_id defaults to the session's open focus task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| session_id | string | Yes | This session UUID. |
| body | string | Yes | The operator's feedback, verbatim. |
| context_line | string | No | One sentence: what was happening when they said it. |
| issue_id | string | No | Identifier or uuid; omit to use the session's open focus span. |
mcp_record_pulse
Record the operator's 1-3 rating of how the SYSTEM is going (never a rating of the operator). 1 = fought it, 2 = fine, 3 = worked well. issue_id defaults to the session's open focus task.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| session_id | string | Yes | This session UUID. |
| rating | integer | Yes | 1 = fought it · 2 = fine · 3 = worked well |
| source | string | Yes | 'end' = the /end sign-off; 'random' = the daily mid-session ask One of: "end", "random". |
| note | string | No | The operator's words, verbatim. |
| issue_id | string | No | Identifier or uuid; omit to use the session's open focus span. |
mcp_task_focus
Start, switch, or clear this session's task focus. 'start'/'switch' close any open span for this session, open a new one on issue_id, and return the task's context pack. 'clear' closes the open span. The operator identity comes from the key.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| action | string | Yes | One of: "start", "switch", "clear". |
| session_id | string | Yes | This session UUID (a correlator, not identity). |
| issue_id | string | No | Required for 'start'/'switch': identifier or uuid. |
| model | string | No | Self-reported model, recorded on the span. |
| effort | string | No | Self-reported reasoning effort, recorded on the span. |
| project_id | string | No | Optional project uuid active when focus started. |
mcp_trigger_comms_check
Queue the comms router for this client ('check comms'): emits comms/route.requested and returns immediately. It does NOT block on the comms sync. Re-fetch the queue shortly after for results.
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
Org relationship
mcp_get_credits
Article-credit balance for one organization in a month (default current UTC month). Contract allowance minus articles scheduled that month.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
| month | string | No | — |
mcp_get_organization
Full detail for one organization named by organization_id or client_slug: brand, contract, review settings, the operator roster, and project/article counts.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
mcp_invite_user_to_org
Invite a user (by email) to an organization. Creates a pending organization_invitations row and sends the invite email best-effort. Requires organization_id + confirm_org (HI-3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| string | Yes | — | |
| first_name | string | No | — |
| last_name | string | No | — |
mcp_list_organizations
List organizations you may act on: id, name, client_slug, whether it carries a contract, and created_at. An operator sees only the orgs it is assigned to; a platform admin sees every active org. Bounded and paginated (HI-5).
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | — |
| offset | integer | No | — |
mcp_publish_linear_project
Publish a Linear project to the client's portal with zero admin involvement. Ensures the org has a linked Linear initiative (adopts one whose name matches the org, else creates it), adds the project to it, tags it with the client's project label, defaults an empty lead to the creator, and syncs the portal mirror inline — the project is live on /projects when this returns. Idempotent: re-running on a published project is a no-op success. `client_label_set: false` means the publish succeeded but the label did not — flag it, do not retry. Requires organization_id + confirm_org (HI-3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| linear_project_id | string | No | The Linear project uuid to publish. Omit to only ensure the initiative exists. |
mcp_set_contract
Set an organization's contract (organizations.contract jsonb) — this drives the article credit allowance. articles_per_month is required; other fields merge over the existing contract. Requires organization_id + confirm_org (HI-3). Returns the new credit balance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| articles_per_month | integer | Yes | — |
| duration_months | integer | No | — |
| start_date | string | No | — |
| auto_renew | boolean | No | — |
Admin plane
mcp_assign_operator
Assign an existing operator (by email) to an organization — inserts an operator_org_assignments row. The operator must already exist: an unknown email is 404 operator_not_found, invite them via /admin first. Requires organization_id + confirm_org (HI-3). The operator email is the acting subject, never an identity input.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| operator_email | string | Yes | — |
| role | string | No | — |
mcp_create_organization
Create a new organization. confirm_org must equal the new org's client_slug (or, if no slug is given, its name) — the typo-guard for a create, since the org has no id yet. Owner/member wiring (auth.users) is out of scope; this seeds the organizations row only.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | — |
| confirm_org | string | Yes | Must equal the new org's client_slug, or its name when no slug is given — the create's typo-guard (the org has no id yet). |
| client_slug | string | No | The new org's portal handle (organizations.client_slug), e.g. 'pointone'. |
| url | string | No | — |
| brand | string | No | — |
| brand_description | string | No | — |
| contract | object | No | — |
mcp_get_org_overview
A single-org rollup for any organization: project count, task-status distribution (mirrored Linear issues by state_type), article count, and the current-month credit usage. Reuses getProjectsForOrg and computeCreditBalance; an org whose Linear source is not configured reports zero projects with a note rather than failing.
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | No | The target organization id. Provide this OR client_slug. |
| client_slug | string | No | The target client's slug (organizations.client_slug), e.g. 'pointone'. |
mcp_operator_dashboard_stats
Fleet-wide operator dashboard aggregations (all orgs): overdue tasks, work-type distribution, per-operator end-of-session pulse, per-operator feedback notes, and tasks completed per operator. Any source unavailable locally degrades in place with a reason rather than failing the tool.
No parameters
mcp_revoke_operator
Revoke an operator's access to an organization — stamps revoked_at on the live operator_org_assignments row. Requires organization_id + confirm_org (HI-3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| organization_id | string | Yes | The target organization id. Writes name their org by uuid, never by slug. |
| confirm_org | string | Yes | Must equal the target org's client_slug — the cross-org write guard (HI-3). A mismatch is rejected before anything is written. |
| operator_email | string | Yes | — |
Operator keys
An operator key is minted by an inseeq admin on Operator accounts in the admin portal (https://admin.staging.inseeq.com/operators/accounts). It is shown once, at creation — inseeq stores only a hash, so a lost key is rotated, never recovered. The operator console itself — the Needs-you queue, each organization's boards and its client-key management — lives on that same host (https://admin.staging.inseeq.com/); its old app.*/operators URLs redirect there. The key carries the operator's identity: the organizations it can reach are that operator's live assignments, and every call stamps last_used_at so a forgotten key is visible.
| Action | Effect |
|---|---|
| Mint | A new key for one operator, with a label. Copy it there and then. |
| Rotate | Mints a replacement with the same label and revokes the old one immediately — the old key answers 401 on its next call, so swap the environment variable first. |
| Revoke | Takes the key out of service at once. There is no undo; mint a new one. |
| Disable the operator | Every key that operator holds stops verifying — one switch for offboarding. |
Treat a key as a credential
A key is the whole authentication story — anyone holding it acts as that operator across every org they are assigned to. Keep it in an environment variable or a secret store, never in a committed file, and revoke it the moment it may have leaked.
Client keys are self-service instead: an organization admin generates one under Settings → API keys.