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
OAuth (recommended)
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/mcpwith:
{
"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, andcall_mcp.
Authentication
| Item | Detail |
|---|---|
| OAuth | MCP 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 management | Name, optional expiry, enable/disable in the app |
| Scope | mcp — platform MCP access for that user |
| Invalid / missing credentials | HTTP 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)
| Action | How you are charged |
|---|---|
ask | AI 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 history | Light AI ranking usage (same credit wallet). If balance is too low, the server falls back to free keyword matching. |
Billable tools inside ask | Charged 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)
| Action | Behavior |
|---|---|
list_agents, get_agent, list_agent_tools, list_mcps, get_mcp_details | Free catalog reads |
recommend_agents with a single message / no history | Free keyword match against the catalog |
call_agent_tool, call_mcp | Same 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):
| Field | Type | Notes |
|---|---|---|
message | string | Shorthand → one user turn (1–32000 chars) |
messages | array | OpenAI-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.chunkdeltas 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:
| Field | Required | Notes |
|---|---|---|
slug | yes | Agent 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:
| Field | Notes |
|---|---|
message or messages | Same shape as ask (one required) |
limit | Optional 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:
| Field | Required | Notes |
|---|---|---|
agentSlug | yes | Target agent |
toolName | yes | Tool on that agent’s MCP |
arguments | no | Object passed to the child tool |
message / messages | no | Optional 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:
| Field | Required | Notes |
|---|---|---|
slug | yes | Target MCP (agent slug) |
tool | if the MCP has > 1 tool | Tool name on that MCP |
arguments | no | Object passed to the child tool |
message / messages | no | Optional 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
| Code | Typical cause |
|---|---|
rate_limit_exceeded | Too many requests in the sliding window |
quota_exceeded | Soft daily message or tool-run limit reached |
INSUFFICIENT_CREDITS | Wallet balance is zero (top up to continue) |
not_found | Unknown or inaccessible agent / resource |
ask_failed | Unexpected failure inside ask |
recommend_failed | Bad input or recommend pipeline error |
tool_call_failed | Child tool missing or execution failed |
TOOL_REQUIRED | call_mcp omitted tool on an MCP that has more than one tool |
NO_TOOLS / TOOL_NOT_FOUND | Target MCP has no tools, or tool does not exist |
MCP_AUTH_REQUIRED | Complete OAuth for that agent in the app |
MCP_TOKEN_REQUIRED | Set / refresh the personal MCP bearer token in the app |
SECRET_REQUIRED | Tool needs user secrets configured in the app |
| (HTTP gate) Invalid token | Missing/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
onprogressandresetTimeoutOnProgress: truefor longaskcalls. - There is no server-side chat session. Resend
messageseach 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
messagefor chat-friendly UIs
Related links
- API keys:
/app/settings/api-keys - Billing:
/app/billing - Pricing:
/pricing - This doc:
https://agorch.io/docs/mcp