Documentation

Platform MCP

How to connect clients to https://agorch.io/mcp, call tools, handle errors, and understand usage-based credits.

Last updated: September 18, 2026

agorch.io exposes a platform MCP endpoint: one Streamable HTTP surface that talks to the home orchestrator and can call specialist agents (MCP of MCPs).

  • Endpoint: https://agorch.io/mcp
  • Auth: OAuth (sign in with your agorch.io account) or bearer API keys from App → API Keys (/app/settings/api-keys)
  • Billing: same prepaid USD credits as the in-app workspace — no MCP access fee and no extra markup for calling Agorch over MCP

Use this page as the reference for tools, inputs, responses, errors, and how usage is charged.


Quick start

Point your MCP client at https://agorch.io/mcp with no API key. The client discovers OAuth, opens the agorch.io login page, and you authorize it with your existing account (Google).

{
  "mcpServers": {
    "agorch": {
      "url": "https://agorch.io/mcp"
    }
  }
}

Bearer API key

  • Create an account and open App → API Keys.
  • Create a key. The full secret (agorchio_sk_…) is shown once.
  • Point your MCP client at https://agorch.io/mcp with:
{
  "mcpServers": {
    "agorch": {
      "url": "https://agorch.io/mcp",
      "headers": {
        "Authorization": "Bearer agorchio_sk_YOUR_KEY"
      }
    }
  }
}
  • List tools in the client. You should see ask, list_agents, recommend_agents, get_agent, list_agent_tools, call_agent_tool, list_mcps, get_mcp_details, and call_mcp.

Authentication

ItemDetail
OAuthMCP clients follow RFC 9728 discovery, then you sign in at /auth (same Google login as the app) and approve access
Header (API key)Authorization: Bearer agorchio_sk_…
Key managementName, optional expiry, enable/disable in the app
Scopemcp — platform MCP access for that user
Invalid / missing credentialsHTTP 401 with WWW-Authenticate pointing at protected resource metadata

OAuth and API keys are equivalent for tools: catalog visibility and agent access follow the authenticated user (global agents + agents they own).


Billing and cost

agorch.io is prepaid usage-based (no subscription). Platform MCP uses the same wallet and pricing as in-app chat and tool runs. There is no MCP surcharge.

What costs credits (wallet debit)

ActionHow you are charged
askAI model usage for the request (input/output, including cached input when reported). If the orchestrator uses billable built-in tools (for example web search), those units are added to the same debit.
recommend_agents with conversation historyLight AI ranking usage (same credit wallet). If balance is too low, the server falls back to free keyword matching.
Billable tools inside askCharged when actually used (for example web search call units), on top of model usage.

Successful ask responses include credits_usage: the USD amount debited for that request (not raw provider token counts).

What does not debit the wallet (but may still require balance / quotas)

ActionBehavior
list_agents, get_agent, list_agent_tools, list_mcps, get_mcp_detailsFree catalog reads
recommend_agents with a single message / no historyFree keyword match against the catalog
call_agent_tool, call_mcpSame as the in-app Run UI: requires a positive credit balance and counts toward the daily soft tool-run quota. The Agorch proxy itself does not add a separate wallet line for the hop. Upstream child MCP servers may still require their own OAuth/token (configured in the app).

Soft daily quotas and rate limits

Before billing, Agorch also enforces:

  • Soft daily quotas for messages (ask) and tool runs (call_agent_tool, call_mcp)
  • Per-user rate limits on chat/tool traffic

When a soft quota is hit you get quota_exceeded. When the wallet is empty you get INSUFFICIENT_CREDITS. Top up at /app/billing or see /pricing.


Tools

ask

Chat with the home orchestrator (same role as in-app home chat). Streams progress when the client provides a progressToken.

Input (provide one of):

FieldTypeNotes
messagestringShorthand → one user turn (1–32000 chars)
messagesarrayOpenAI-style turns, 1–100 items

Message object: { role: "system" | "user" | "assistant" | "tool", content: string, name?, tool_call_id? }.

Success payload (text of the MCP tool result is JSON):

{
  "id": "mcpask_…",
  "object": "chat.completion",
  "created": 1786235913,
  "model": "openai/…",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "credits_usage": 0.01,
  "agorch": { "recommendedAgents": [] }
}
  • credits_usage — USD charged for this call (wallet debit). Raw token counts are not exposed.
  • agorch.recommendedAgents — agents suggested during the turn when applicable.
  • Progress notifications may carry chat.completion.chunk deltas when streaming.

Common errors: rate_limit_exceeded, quota_exceeded, INSUFFICIENT_CREDITS, ask_failed.


list_agents

List agents available to the authenticated user (global + owned).

Input: none.

Success: { "agents": [ { "name", "slug", "description", "icon", "tags", "toolsCount" }, … ] }


get_agent

Details for one agent by slug, including stored tool schemas.

Input:

FieldRequiredNotes
slugyesAgent slug

Success: agent record with tools[] (name, description, inputSchema), plus flags such as needUserAuth / needUserToken.

Errors: not_found — agent missing or not accessible.


list_agent_tools

Tools registered for an agent slug (lighter than full get_agent).

Input: slug (required).

Success: { "slug": "…", "tools": [ { "name", "description", "inputSchema" }, … ] }

Errors: not_found.


recommend_agents

Recommend agents for a request.

Input:

FieldNotes
message or messagesSame shape as ask (one required)
limitOptional integer 1–5 (default 5)

Behavior:

  • No conversation history → free keyword match (reason: "Keyword match against catalog")
  • History present → light LLM ranking when credits allow; otherwise keyword fallback

Success: { "reason": "…", "agents": [ … ] } (same agent summary shape as list_agents).

Errors: recommend_failed (for example missing message/messages).


call_agent_tool

Call a tool on a child agent MCP (MCP of MCPs).

Input:

FieldRequiredNotes
agentSlugyesTarget agent
toolNameyesTool on that agent’s MCP
argumentsnoObject passed to the child tool
message / messagesnoOptional conversation context injected for the child

Success:

{
  "agentSlug": "context7",
  "toolName": "resolve-library-id",
  "result": { … }
}

result is whatever the child MCP returned (often MCP content blocks).

Errors: see table below (not_found, tool_call_failed, MCP_AUTH_REQUIRED, MCP_TOKEN_REQUIRED, SECRET_REQUIRED, quotas, rate limit, insufficient credits).

Agents that need OAuth or a personal bearer token must be connected in the agorch.io app first.


list_mcps

List MCP servers available to the authenticated user (same catalog as agents).

Input: none.

Success: { "mcps": [ { "slug", "name", "description", "icon", "tags", "needUserAuth", "needUserToken", "toolsCount", "toolRequired" }, … ] }

toolRequired is true when toolsCount > 1 — call_mcp then needs tool.


get_mcp_details

Details for one MCP by slug, including tool schemas.

Input: slug (required).

Success: MCP record with tools[], toolsCount, and toolRequired.

Errors: not_found.


call_mcp

Call a tool on a child MCP. If that MCP has more than one tool, tool is required. If it has exactly one, tool may be omitted.

Input:

FieldRequiredNotes
slugyesTarget MCP (agent slug)
toolif the MCP has > 1 toolTool name on that MCP
argumentsnoObject passed to the child tool
message / messagesnoOptional conversation context

Success: { "slug", "tool", "result" }

Errors: TOOL_REQUIRED (response lists available tools), NO_TOOLS, TOOL_NOT_FOUND, plus the same codes as call_agent_tool.


Error shape

Tool failures return MCP isError: true with text that is OpenAI-like error JSON:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "code": "not_found"
  }
}

Codes you should handle

CodeTypical cause
rate_limit_exceededToo many requests in the sliding window
quota_exceededSoft daily message or tool-run limit reached
INSUFFICIENT_CREDITSWallet balance is zero (top up to continue)
not_foundUnknown or inaccessible agent / resource
ask_failedUnexpected failure inside ask
recommend_failedBad input or recommend pipeline error
tool_call_failedChild tool missing or execution failed
TOOL_REQUIREDcall_mcp omitted tool on an MCP that has more than one tool
NO_TOOLS / TOOL_NOT_FOUNDTarget MCP has no tools, or tool does not exist
MCP_AUTH_REQUIREDComplete OAuth for that agent in the app
MCP_TOKEN_REQUIREDSet / refresh the personal MCP bearer token in the app
SECRET_REQUIREDTool needs user secrets configured in the app
(HTTP gate) Invalid tokenMissing/disabled/expired API key, or expired/revoked OAuth token

Streaming and sessions

  • Transport is MCP Streamable HTTP. When tools emit progress, responses may upgrade to SSE.
  • Prefer client onprogress and resetTimeoutOnProgress: true for long ask calls.
  • There is no server-side chat session. Resend messages each call (Chat Completions style). The server truncates very long histories.

Transport priority

  • MCP wire protocol (tools/call, CallToolResult, progress notifications)
  • OpenAI-like JSON inside tool text / progress message for chat-friendly UIs

  • API keys: /app/settings/api-keys
  • Billing: /app/billing
  • Pricing: /pricing
  • This doc: https://agorch.io/docs/mcp