Skip to main content
The ManticScore API exposes a Model Context Protocol (MCP) server over HTTP at /mcp. MCP-compatible clients — like Claude Code, Claude Desktop, and any other agent that speaks the mcp__http transport — can connect to it to invoke orchestrator tools. The endpoint is gated by a per-user bearer token that you mint and manage from your account. It is not part of the user-facing API surface and does not accept Clerk JWTs or session tokens.
This endpoint uses a dedicated MCP bearer token, not the standard Authorization modes documented in the overview. Mint and revoke tokens via the MCP token endpoints on your profile.

Endpoint

POST /mcp/ (and any sub-path under /mcp/) — speaks the MCP streamable HTTP transport. Point your MCP client at https://api.manticscore.com/mcp/ and configure it to send the bearer token below on every request.

Authentication

Every request to /mcp/ must carry a bearer token in the Authorization header:
Tokens have the form mcp_<48 url-safe chars>. They are minted per user via POST /profile/mcp/tokens and resolved server-side to a user_id by SHA-256 hash lookup against the active token store. The hashed bearer is matched against mc_user_mcp_tokens rows where revoked_at IS NULL; on a hit, last_used_at is bumped fire-and-forget and the resolved user_id scopes every tool call (see Per-user scoping below). A legacy single-secret admin path is preserved for system tooling: if the bearer matches orchestrator_mcp_secret (constant-time compare), the request runs in admin/system context with no user_id filter and tools see all rows.
Treat MCP bearer tokens like any other credential. The plaintext is returned exactly once at creation — store it securely. Revoke compromised tokens via DELETE /profile/mcp/tokens/{token_id}.

Per-user scoping

Tools that read or write user-scoped rows automatically filter by the user_id resolved from the bearer token: Stateless tools — select_model, list_agents, get_agent, orchestrator_classify, orchestrator_reset_cache, and ping — are unchanged and do not depend on user_id. When the request authenticates via the admin fallback secret, user_id is None and tools see all rows regardless of owner.

Tools

The MCP server advertises its tools via the standard MCP discovery flow. Your client will pick them up automatically once connected.

ping

Health probe for the MCP transport. Returns the server identity and the current UTC timestamp. Use this to verify connectivity and authentication before invoking other tools. Arguments: none.
Response
boolean
Always true when the call succeeds.
string
Server identity. Currently manticscore-orchestrator.
string
Current server time as an ISO 8601 timestamp in UTC.

decision_log

Append a decision to the orchestrator’s decision log for future reference and learning. The row is embedded asynchronously after insert so the call is not blocked on the embedding round-trip; the embedded text is searchable via decision_search once embedding completes.
string
required
The situation, observations, or inputs that motivated the decision.
string
required
The chosen action or conclusion.
string
Optional UUID linking this decision back to an in-flight task or run.
string
Optional retrospective outcome. Can be filled in later via an out-of-band update.
number
Self-reported confidence of the deciding agent on a 01 scale.
string[]
Free-form categorization tags. Used as an any-match (overlap) filter by decision_search.
Response
string
UUID of the new decision row.
string | null
UUID linking back to a task, if provided on log.
string
The situation that motivated the decision, as supplied by the caller.
string
The chosen action, as supplied by the caller.
string | null
Retrospective outcome, if any.
number | null
Self-reported confidence on a 01 scale.
string[]
Categorization tags, defaulting to an empty list.
string
Insert timestamp as an ISO 8601 string in UTC.
Search past decisions by free-text query and optional tag filter. Tries semantic search first using OpenAI embeddings (text-embedding-3-small, 512-dim); falls back to a case-insensitive ILIKE over context and decision if the semantic search returns no rows or embeddings are unavailable. Returns matching decisions ordered by similarity (semantic) or recency (fallback).
string
required
Natural-language query. Matched against the embedded context + decision text first, then ILIKE’d over the same fields as a fallback.
integer
default:"10"
Maximum number of decisions to return. Clamped to the range 150.
string[]
Any-match (overlap) filter. A decision matches if at least one of its tags appears in this list.
Response
number
Cosine similarity in the range 01, included only on rows returned via the semantic path. Absent on ILIKE-fallback results.
Each row also includes the same id, task_id, context, decision, outcome, confidence, tags, and created_at fields documented under decision_log.

pattern_store

Store a reusable pattern — a named bundle of trigger_conditions and actions — for later retrieval via pattern_match. Both trigger_conditions and actions are free-form JSON objects defined by the calling agent. The row is embedded asynchronously over name + description after insert so the call is not blocked on the embedding round-trip.
string
required
Short, human-readable name for the pattern. Used as the primary text signal for retrieval.
object
required
Free-form JSON describing when the pattern applies (e.g. matchers, predicates, situational tags). Stored as JSONB.
object
required
Free-form JSON describing what to do when the trigger fires (e.g. an action list, a tool plan). Stored as JSONB.
string
Optional longer description. Concatenated with name to produce the embedded text used by pattern_match.
Response
string
UUID of the new pattern row.
string | null
Owning user, resolved from the MCP bearer token. null only when the request authenticated via the admin fallback secret (system context).
string
Pattern name as supplied by the caller.
string | null
Pattern description as supplied by the caller.
object
JSON trigger conditions, returned as a parsed object.
object
JSON action plan, returned as a parsed object.
number
Running average of successful invocations on a 01 scale. Starts at 0 and is updated by increment_usage (server-side helper, not exposed as an MCP tool).
integer
Total number of times the pattern has been invoked. Starts at 0.
string
Insert timestamp as an ISO 8601 string in UTC.
string
Last-update timestamp as an ISO 8601 string in UTC. Equal to created_at on first insert.

pattern_match

Find patterns relevant to a given situation. Tries semantic search first using OpenAI embeddings (text-embedding-3-small, 512-dim) over the embedded name + description text; falls back to a case-insensitive ILIKE over name and description ranked by success_rate then usage_count if the semantic search returns no rows or embeddings are unavailable.
string
required
Natural-language description of the current situation. Matched against the embedded name + description text first, then ILIKE’d over the same fields as a fallback.
integer
default:"10"
Maximum number of patterns to return. Clamped to the range 150.
Response
number
Cosine similarity in the range 01, included only on rows returned via the semantic path. Absent on ILIKE-fallback results.
Each row also includes the same id, user_id, name, description, trigger_conditions, actions, success_rate, usage_count, created_at, and updated_at fields documented under pattern_store.

task_create

Create a new task in the orchestrator. The new row is inserted with status = pending, and the creation is recorded in the audit log as a transition from null to pending.
string
required
Short, human-readable title for the task.
string
Optional longer description of the task.
string
default:"medium"
One of low, medium, high, or urgent.
string
Optional label identifying where the task originated (e.g. mcp, chat, inngest). Used as the actor on the initial null → pending transition row when set; defaults to mcp if omitted.
string
Optional identifier of the agent responsible for the task.
string
Optional UUID of a parent task. The parent must exist; if the parent is later deleted, this field is set to null (ON DELETE SET NULL).
object
Free-form JSON metadata. Stored as JSONB. Defaults to {}.
Response
string
UUID of the new task row.
string | null
Owning user, resolved from the MCP bearer token. null only when the request authenticated via the admin fallback secret (system context).
string
Task title as supplied by the caller.
string | null
Task description as supplied by the caller.
string
One of pending, approved, in_progress, blocked, review, completed, failed, or cancelled. Always pending immediately after task_create.
string
One of low, medium, high, or urgent.
string | null
Origin label as supplied by the caller.
string | null
Assigned agent identifier, if any.
string | null
Parent task UUID, if any.
object
Task metadata as a parsed JSON object. Defaults to an empty object.
string
Insert timestamp as an ISO 8601 string in UTC.
string
Last-update timestamp as an ISO 8601 string in UTC. Equal to created_at on first insert.
string | null
Set automatically when the task transitions to completed. null until then.

task_update

Update a task. Use this to change the status (via the state machine) and/or update non-status fields like title, description, priority, assigned agent, or metadata. Status changes and field changes can be combined in a single call. For status changes, prefer action over status — actions are validated against the state machine and produce clearer errors. The legal action and target-status pairs are: Illegal transitions raise an error listing the legal actions from the current state. Transitioning into completed automatically sets completed_at. Every transition appends a row to the task’s audit log.
string
required
UUID of the task to update.
string
Target status. Validated against the state machine. Prefer action instead.
string
State-machine action to apply: one of approve, start, block, unblock, submit, reject, complete, fail, or cancel.
string
New title.
string
New description.
string
New priority. One of low, medium, high, or urgent.
string
New assigned agent identifier.
object
Free-form JSON metadata. Merged into the existing metadata using JSONB concat (||), not replaced — top-level keys present in the new object overwrite existing keys, and other keys are preserved.
string
Optional human-readable reason for the transition. Recorded on the audit row when a status change is applied.
string
Optional identifier of the actor performing the transition. Recorded on the audit row.
The response is the updated task row, with the same shape as task_create.

task_list

List tasks with optional filters. Returns rows newest-first by created_at.
string
Filter by status. One of pending, approved, in_progress, blocked, review, completed, failed, or cancelled.
string
Filter by priority. One of low, medium, high, or urgent.
string
Filter by assigned agent identifier.
integer
default:"50"
Maximum number of tasks to return. Clamped to the range 1200.
The response is an array of task rows, each with the same shape as task_create.

task_get

Get a task with its full transition history and the list of valid next actions from its current state.
string
required
UUID of the task to fetch.
Response
object
The task row, with the same shape as the response from task_create.
object[]
Audit log of every transition for this task, ordered oldest-first.
string
UUID of the transition row.
string
UUID of the task this transition belongs to.
string | null
Previous status. null for the initial creation row.
string
New status.
string | null
Reason recorded with the transition, if any.
string | null
Actor recorded with the transition, if any.
string
Transition timestamp as an ISO 8601 string in UTC.
string[]
The state-machine actions that are legal from the task’s current status. Empty when the task is in a terminal state (completed, cancelled).

context_for_task

Aggregate everything an agent needs to act on a task: the task itself, its transition history, related decisions, child tasks, matching patterns, and the list of valid next actions. Equivalent to combining task_get, decision_search (filtered by task_id), task_list (filtered by parent), and pattern_match (over the task title + description) into a single call.
string
required
UUID of the task to gather context for.
Response
object
The task row, with the same shape as the response from task_create.
object[]
Audit log of every transition for this task, oldest-first. Same shape as task_get.transitions.
Decisions that reference this task_id. Each row has the same shape as a decision_log response.
object[]
Tasks whose parent_task_id equals this task’s id, newest-first, capped at 200. Each row has the same shape as a task_create response.
object[]
Up to 10 patterns matched against the task’s title and description via pattern_match. Empty if both fields are empty.
string[]
The state-machine actions that are legal from the task’s current status.

route_task

Analyze a task and recommend which agent + model should handle it. Routing is a pure, keyword-based capability score — no LLM call. By default, returns a recommendation only without mutating the task. If assign is true, also writes the routing result into the task’s metadata.routing, sets assigned_agent, and appends a routing decision to the orchestrator’s decision log via decision_log.
string
required
UUID of the task to route. The task must exist.
boolean
default:"false"
When true, applies the routing decision to the task: updates assigned_agent, merges a routing block into metadata (with agent_id, model, confidence, reasoning, routed_at), and writes a routing decision audit row tagged routing, auto-assign, and the agent id. When false, the task is left untouched.
Response
object
Routing decision.
object
The selected agent record from the registry. Same shape as a row from list_agents.
string
Concrete Claude model id assigned to the task. Currently one of claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-7 — sourced from the agent’s model field.
number
Self-reported routing confidence on a 01 scale, derived from the best-match capability score.
string
Short human-readable explanation of why this agent was picked, including the detected capabilities, the winning score, the model, the task priority, and the source channel when set.
object[]
Up to three runner-up agents, ordered by score. Each entry has an agent_id, confidence, and reason describing the matched capabilities.
object
When assign=false, a trimmed view of the task (id, title, status). When assign=true, the full updated task row with the same shape as the task_create response, including the merged metadata.routing block.
string
Either recommendation_only (when assign=false) or assigned (when assign=true).

select_model

Map a task complexity tier to a concrete Claude model id. Pure lookup — no agent registry interaction. Use this when an agent has already decided what kind of work it’s doing and just needs a model name.
string
required
One of fast, balanced, or powerful. Unknown tiers raise an error.
string
Optional free-text label (e.g. a task title or short description). Echoed back in the response for caller-side logging; not used to influence the choice.
Response
string
The tier supplied by the caller, echoed back.
string
The concrete Claude model id for the tier. Mapping: fast → claude-haiku-4-5, balanced → claude-sonnet-4-6, powerful → claude-opus-4-7.
string | null
The context argument as supplied, or null if omitted.
string
Short usage guidance for the tier. Useful for prompts that surface “why this model”.

list_agents

List every registered agent with its capabilities, transport, model, and cost tier. The registry is currently a static set of five agents (claude-code, research-agent, triage-agent, api-agent, openclaw-discord) — used by route_task to decide where work goes. Arguments: none.
Response
string
Stable agent identifier. Use this with get_agent and as the value of assigned_agent on tasks.
string
Human-readable agent name.
string
Short description of what the agent is best at.
string[]
Capability tags used by the router for keyword-based scoring. Examples: code, research, triage, api, discord, conversation.
string
Default Claude model the agent runs on. One of claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-7.
string
How the orchestrator reaches the agent. One of mcp-stdio, mcp-http, or openclaw-agent.
integer
Soft concurrency budget — the maximum number of in-flight runs the orchestrator will dispatch to this agent at once.
string
One of low, medium, or high. Used by route_task to bias toward cheaper agents on low-priority work and pricier agents on urgent / high priority work.

get_agent

Get the registry entry for a single agent by id.
string
required
The agent identifier (e.g. claude-code, research-agent, triage-agent, api-agent, openclaw-discord). Unknown ids raise an error.
The response is a single agent row with the same shape as an entry returned by list_agents.

orchestrator_classify

Classify a task title (and optional description / project name) into a category and an actionability bucket using regex pattern matching. Pure function — does not create or modify any rows. Useful for triage flows that need to decide where a new task should land before calling task_create.
string
required
Task title to classify.
string
Optional longer description. Concatenated with title and project to form the matched text.
string
Optional project name. Concatenated into the matched text and also used to disambiguate ties (e.g. project names containing content, calendar, backlog, or goal boost the corresponding category).
Response
string
Best-fit category. One of engineering, research, content, integration, personal, goal, read, or unknown when nothing matches.
string
Suggested handler bucket: agent (an autonomous agent can do it), human (needs a person), hybrid (agent drafts, human reviews), or defer (long-horizon goal — surface, don’t action). Mapping: engineering/research/integration → agent, personal → human, content/read/unknown → hybrid, goal → defer.
number
Self-reported classification confidence on a 01 scale, derived from the winning category’s score.
string
Short string showing the winning category and score plus up to three runners-up. Useful for debugging classification calls.

orchestrator_reset_cache

Clear the orchestrator’s in-memory sync cache and return the number of keys that were cleared.
This is a legacy hook preserved for parity with the previous Node orchestrator’s Asana polling loop. The polling loop is being replaced by Inngest workflows; today the cache is empty in steady state and this tool is effectively a no-op. Future Inngest workflows may write into the cache, at which point this becomes useful again.
Arguments: none.
Response
integer
The number of cache entries that were dropped by this call.

Connecting from Claude Code

Mint a token from your profile (see Manage MCP bearer tokens), then configure Claude Code (or any MCP HTTP client) with the endpoint URL and the plaintext token returned at creation. The exact configuration steps depend on your client; consult its documentation for the mcp__http transport.
Example client config
Once connected, run the ping tool to confirm the transport is healthy.