MCP server — orchestrator over HTTP

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:

Authorization: Bearer <mcp_token>

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.

Status	Condition
`401 Unauthorized`	The `Authorization` header is missing or does not start with `Bearer` .
`403 Forbidden`	The bearer token is not a valid active user token and does not match the admin secret.
`503 Service Unavailable`	The MCP route is not configured (database pool unavailable).

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:

decision_log and pattern_store insert with the resolved user_id.
decision_search and pattern_match filter results to the calling user’s rows.
task_create inserts with the resolved user_id. task_list, task_get, task_update, route_task, and context_for_task verify task ownership before reading or mutating; cross-user task access returns an error.

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

{
  "pong": true,
  "server": "manticscore-orchestrator",
  "ts": "2026-04-29T07:55:00.000000+00:00"
}

pong

boolean

Always true when the call succeeds.

server

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.

context

string

required

The situation, observations, or inputs that motivated the decision.

decision

string

required

The chosen action or conclusion.

task_id

string

Optional UUID linking this decision back to an in-flight task or run.

outcome

string

Optional retrospective outcome. Can be filled in later via an out-of-band update.

confidence

number

Self-reported confidence of the deciding agent on a 0–1 scale.

`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).

query

string

required

Natural-language query. Matched against the embedded context + decision text first, then ILIKE’d over the same fields as a fallback.

limit

integer

default:"10"

Maximum number of decisions to return. Clamped to the range 1–50.

`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.

name

string

required

Short, human-readable name for the pattern. Used as the primary text signal for retrieval.

trigger_conditions

object

required

Free-form JSON describing when the pattern applies (e.g. matchers, predicates, situational tags). Stored as JSONB.

actions

object

required

Free-form JSON describing what to do when the trigger fires (e.g. an action list, a tool plan). Stored as JSONB.

description

string

Optional longer description. Concatenated with name to produce the embedded text used by pattern_match.

Response

{
  "id": "8c2e1a44-3f02-4b1d-bd5e-9d4a3b2c8101",
  "user_id": null,
  "name": "Cascade retrieval on judge failure",
  "description": "When the judge stage emits a failure event, fall back to mechanical ranking and continue.",
  "trigger_conditions": {
    "event": "stage:judge/failed"
  },
  "actions": {
    "steps": ["use_mechanical_rank", "continue_to_analyze"]
  },
  "success_rate": 0,
  "usage_count": 0,
  "created_at": "2026-04-29T08:30:00.000000+00:00",
  "updated_at": "2026-04-29T08:30:00.000000+00:00"
}

string

UUID of the new pattern row.

user_id

string | null

Owning user, resolved from the MCP bearer token. null only when the request authenticated via the admin fallback secret (system context).

name

string

Pattern name as supplied by the caller.

description

string | null

Pattern description as supplied by the caller.

trigger_conditions

object

JSON trigger conditions, returned as a parsed object.

actions

object

JSON action plan, returned as a parsed object.

success_rate

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).

usage_count

integer

Total number of times the pattern has been invoked. Starts at 0.

created_at

string

Insert timestamp as an ISO 8601 string in UTC.

updated_at

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.

situation

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.

limit

integer

default:"10"

Maximum number of patterns to return. Clamped to the range 1–50.

Response

[
  {
    "id": "8c2e1a44-3f02-4b1d-bd5e-9d4a3b2c8101",
    "user_id": null,
    "name": "Cascade retrieval on judge failure",
    "description": "When the judge stage emits a failure event, fall back to mechanical ranking and continue.",
    "trigger_conditions": {
      "event": "stage:judge/failed"
    },
    "actions": {
      "steps": ["use_mechanical_rank", "continue_to_analyze"]
    },
    "success_rate": 0.82,
    "usage_count": 17,
    "created_at": "2026-04-29T08:30:00.000000+00:00",
    "updated_at": "2026-04-29T08:30:00.000000+00:00",
    "similarity": 0.79
  }
]

similarity

number

Cosine similarity in the range 0–1, 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.

title

string

required

Short, human-readable title for the task.

description

string

Optional longer description of the task.

priority

string

default:"medium"

One of low, medium, high, or urgent.

source_channel

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.

assigned_agent

string

Optional identifier of the agent responsible for the task.

parent_task_id

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).

metadata

object

Free-form JSON metadata. Stored as JSONB. Defaults to {}.

Response

{
  "id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
  "user_id": null,
  "title": "Investigate stage-2 retrieval regression",
  "description": "Recall dropped 8% on golden eval after the cascade rewrite.",
  "status": "pending",
  "priority": "high",
  "source_channel": "mcp",
  "assigned_agent": null,
  "parent_task_id": null,
  "metadata": {},
  "created_at": "2026-04-29T08:30:00.000000+00:00",
  "updated_at": "2026-04-29T08:30:00.000000+00:00",
  "completed_at": null
}

string

UUID of the new task row.

user_id

string | null

Owning user, resolved from the MCP bearer token. null only when the request authenticated via the admin fallback secret (system context).

title

string

Task title as supplied by the caller.

description

string | null

Task description as supplied by the caller.

status

string

One of pending, approved, in_progress, blocked, review, completed, failed, or cancelled. Always pending immediately after task_create.

priority

string

One of low, medium, high, or urgent.

source_channel

string | null

Origin label as supplied by the caller.

assigned_agent

string | null

Assigned agent identifier, if any.

parent_task_id

string | null

Parent task UUID, if any.

metadata

object

Task metadata as a parsed JSON object. Defaults to an empty object.

created_at

string

Insert timestamp as an ISO 8601 string in UTC.

updated_at

string

Last-update timestamp as an ISO 8601 string in UTC. Equal to created_at on first insert.

completed_at

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:

Action	From	To
`approve`	`pending`	`approved`
`start`	`approved`	`in_progress`
`block`	`in_progress`	`blocked`
`unblock`	`blocked`	`in_progress`
`submit`	`in_progress`	`review`
`reject`	`review`	`in_progress`
`complete`	`review`	`completed`
`fail`	`in_progress`	`failed`
`cancel`	`pending`, `approved`, `in_progress`, `blocked`, `review`, `failed`	`cancelled`

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.

task_id

string

required

UUID of the task to update.

status

string

Target status. Validated against the state machine. Prefer action instead.

action

string

State-machine action to apply: one of approve, start, block, unblock, submit, reject, complete, fail, or cancel.

title

string

New title.

description

string

New description.

priority

string

New priority. One of low, medium, high, or urgent.

assigned_agent

string

New assigned agent identifier.

metadata

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.

reason

string

Optional human-readable reason for the transition. Recorded on the audit row when a status change is applied.

actor

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.

status

string

Filter by status. One of pending, approved, in_progress, blocked, review, completed, failed, or cancelled.

priority

string

Filter by priority. One of low, medium, high, or urgent.

assigned_agent

string

Filter by assigned agent identifier.

limit

integer

default:"50"

Maximum number of tasks to return. Clamped to the range 1–200.

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.

task_id

string

required

UUID of the task to fetch.

Response

{
  "task": {
    "id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
    "user_id": null,
    "title": "Investigate stage-2 retrieval regression",
    "description": "Recall dropped 8% on golden eval after the cascade rewrite.",
    "status": "in_progress",
    "priority": "high",
    "source_channel": "mcp",
    "assigned_agent": "agent.research",
    "parent_task_id": null,
    "metadata": {},
    "created_at": "2026-04-29T08:30:00.000000+00:00",
    "updated_at": "2026-04-29T09:05:00.000000+00:00",
    "completed_at": null
  },
  "transitions": [
    {
      "id": "0c0a1f10-9e48-4f29-b4f2-3c1c4d2a8a01",
      "task_id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
      "from_status": null,
      "to_status": "pending",
      "reason": null,
      "actor": "mcp",
      "created_at": "2026-04-29T08:30:00.000000+00:00"
    },
    {
      "id": "0c0a1f10-9e48-4f29-b4f2-3c1c4d2a8a02",
      "task_id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
      "from_status": "pending",
      "to_status": "approved",
      "reason": "scoped",
      "actor": "agent.triage",
      "created_at": "2026-04-29T08:45:00.000000+00:00"
    },
    {
      "id": "0c0a1f10-9e48-4f29-b4f2-3c1c4d2a8a03",
      "task_id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
      "from_status": "approved",
      "to_status": "in_progress",
      "reason": null,
      "actor": "agent.research",
      "created_at": "2026-04-29T09:05:00.000000+00:00"
    }
  ],
  "valid_actions": ["block", "submit", "fail", "cancel"]
}

task

object

The task row, with the same shape as the response from task_create.

transitions

object[]

Audit log of every transition for this task, ordered oldest-first.

transitions[].id

string

UUID of the transition row.

transitions[].task_id

string

UUID of the task this transition belongs to.

transitions[].from_status

string | null

Previous status. null for the initial creation row.

transitions[].to_status

string

New status.

transitions[].reason

string | null

Reason recorded with the transition, if any.

transitions[].actor

string | null

Actor recorded with the transition, if any.

transitions[].created_at

string

Transition timestamp as an ISO 8601 string in UTC.

valid_actions

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.

task_id

string

required

UUID of the task to gather context for.

Response

{
  "task": { "...": "same shape as task_create response" },
  "transitions": [],
  "related_decisions": [],
  "subtasks": [],
  "matching_patterns": [],
  "valid_actions": ["block", "submit", "fail", "cancel"]
}

task

object

The task row, with the same shape as the response from task_create.

transitions

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.

subtasks

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.

matching_patterns

object[]

Up to 10 patterns matched against the task’s title and description via pattern_match. Empty if both fields are empty.

valid_actions

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.

task_id

string

required

UUID of the task to route. The task must exist.

assign

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

{
  "routing": {
    "agent": {
      "id": "claude-code",
      "name": "Claude Code",
      "description": "Full-featured coding agent — builds features, fixes bugs, manages repos",
      "capabilities": ["code", "git", "testing", "deployment", "refactoring", "architecture"],
      "model": "claude-opus-4-7",
      "transport": "mcp-stdio",
      "max_concurrent": 1,
      "cost_tier": "high"
    },
    "model": "claude-opus-4-7",
    "confidence": 0.74,
    "reasoning": "Detected capabilities: code(3), api(1). Best match: Claude Code (score 35). Model: claude-opus-4-7. Priority: high. Source: chat",
    "alternates": [
      {
        "agent_id": "api-agent",
        "confidence": 0.42,
        "reason": "Score 18: api"
      }
    ]
  },
  "task": {
    "id": "5b2c0c4f-1a2e-4d63-9b1d-2c2f0a3a8b14",
    "title": "Fix stage-2 retrieval regression in the API",
    "status": "pending"
  },
  "action": "recommendation_only"
}

routing

object

Routing decision.

routing.agent

object

The selected agent record from the registry. Same shape as a row from list_agents.

routing.model

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.

routing.confidence

number

Self-reported routing confidence on a 0–1 scale, derived from the best-match capability score.

routing.reasoning

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.

routing.alternates

object[]

Up to three runner-up agents, ordered by score. Each entry has an agent_id, confidence, and reason describing the matched capabilities.

task

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.

action

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.

tier

string

required

One of fast, balanced, or powerful. Unknown tiers raise an error.

context

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

{
  "tier": "balanced",
  "model": "claude-sonnet-4-6",
  "context": "summarize a research run",
  "guidance": "Best for: general tasks, API calls, research, conversation. Cost-tier: Sonnet."
}

tier

string

The tier supplied by the caller, echoed back.

model

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.

context

string | null

The context argument as supplied, or null if omitted.

guidance

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

[
  {
    "id": "claude-code",
    "name": "Claude Code",
    "description": "Full-featured coding agent — builds features, fixes bugs, manages repos",
    "capabilities": ["code", "git", "testing", "deployment", "refactoring", "architecture"],
    "model": "claude-opus-4-7",
    "transport": "mcp-stdio",
    "max_concurrent": 1,
    "cost_tier": "high"
  },
  {
    "id": "research-agent",
    "name": "Research Agent",
    "description": "Fast agent for web research, documentation lookup, and data gathering",
    "capabilities": ["research", "web-search", "summarization", "data-extraction"],
    "model": "claude-sonnet-4-6",
    "transport": "mcp-http",
    "max_concurrent": 3,
    "cost_tier": "medium"
  }
]

string

Stable agent identifier. Use this with get_agent and as the value of assigned_agent on tasks.

name

string

Human-readable agent name.

description

string

Short description of what the agent is best at.

capabilities

string[]

Capability tags used by the router for keyword-based scoring. Examples: code, research, triage, api, discord, conversation.

model

string

Default Claude model the agent runs on. One of claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-7.

transport

string

How the orchestrator reaches the agent. One of mcp-stdio, mcp-http, or openclaw-agent.

max_concurrent

integer

Soft concurrency budget — the maximum number of in-flight runs the orchestrator will dispatch to this agent at once.

cost_tier

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.

agent_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.

title

string

required

Task title to classify.

description

string

Optional longer description. Concatenated with title and project to form the matched text.

project

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

{
  "category": "engineering",
  "actionability": "agent",
  "confidence": 0.6,
  "reason": "engineering(6), also: api(2)"
}

`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

{
  "cleared_keys": 0
}

cleared_keys

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

{
  "mcpServers": {
    "manticscore": {
      "transport": "http",
      "url": "https://api.manticscore.com/mcp/",
      "headers": {
        "Authorization": "Bearer mcp_<your_token>"
      }
    }
  }
}

Once connected, run the ping tool to confirm the transport is healthy.

Overview

Projects & Research

Build & Forge

Intelligence & Chat

Integrations & Ship

MCP server — orchestrator over HTTP

Endpoint

Authentication

Per-user scoping

Tools

`ping`

`decision_log`

`decision_search`

`pattern_store`

`pattern_match`

`task_create`

`task_update`

`task_list`

`task_get`

`context_for_task`

`route_task`

`select_model`

`list_agents`

`get_agent`

`orchestrator_classify`

`orchestrator_reset_cache`

Connecting from Claude Code

Overview

Projects & Research

Build & Forge

Intelligence & Chat

Integrations & Ship

Documentation Index

​Endpoint

​Authentication

​Per-user scoping

​Tools

​ping

​decision_log

​decision_search

​pattern_store

​pattern_match

​task_create

​task_update

​task_list

​task_get

​context_for_task

​route_task

​select_model

​list_agents

​get_agent

​orchestrator_classify

​orchestrator_reset_cache

​Connecting from Claude Code

Endpoint

Authentication

Per-user scoping

Tools

`ping`

`decision_log`

`decision_search`

`pattern_store`

`pattern_match`

`task_create`

`task_update`

`task_list`

`task_get`

`context_for_task`

`route_task`

`select_model`

`list_agents`

`get_agent`

`orchestrator_classify`

`orchestrator_reset_cache`

Connecting from Claude Code