/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:
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.
Per-user scoping
Tools that read or write user-scoped rows automatically filter by theuser_id resolved from the bearer token:
decision_logandpattern_storeinsert with the resolveduser_id.decision_searchandpattern_matchfilter results to the calling user’s rows.task_createinserts with the resolveduser_id.task_list,task_get,task_update,route_task, andcontext_for_taskverify task ownership before reading or mutating; cross-user task access returns an error.
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
0–1 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
0–1 scale.string[]
Categorization tags, defaulting to an empty list.
string
Insert timestamp as an ISO 8601 string in UTC.
decision_search
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
1–50.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
0–1, included only on rows returned via the semantic path. Absent on ILIKE-fallback results.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
0–1 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
1–50.Response
number
Cosine similarity in the range
0–1, included only on rows returned via the semantic path. Absent on ILIKE-fallback results.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.
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
1–200.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
0–1 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.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
0–1 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.
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 themcp__http transport.
Example client config
ping tool to confirm the transport is healthy.