MCP tools

Calling the MCP server speaks JSON-RPC 2.0 over HTTP POST to /api/mcp. Every tool lives under the standard tools/call method:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": { "question": "..." }
  }
}

ask

Primary tool. Auto-routes to the best-matching agent in your subscription.

Arguments:

• question (string, 1–8000 chars, required) — your question in natural language
• conversationId (string, optional) — continues a previous task; omit to start a new conversation (consumes a task slot)

Returns:

{
  "answer": "…",
  "agentUsed": { "id": "…", "name": "…", "slug": "…", "creator": "…" },
  "conversationId": "…",
  "messageId": "…",
  "escalationAvailable": true
}

ask_agent

Pin a specific agent by ID. Same arguments as ask plus agentId (required).

Use when the caller knows which agent should answer — either from a prior list_my_agents or from the PROAGENTME_DEFAULT_AGENT env var in the stdio wrapper.

list_my_agents

No arguments. Returns agents the user can run, filtered by subscription tier's allowed model tiers.

Returns:

{
  "agents": [
    {
      "id": "uuid",
      "name": "…",
      "slug": "…",
      "description": "…",
      "creator": { "name": "…", "slug": "…" },
      "modelTier": "fast|balanced|advanced"
    }
  ]
}

escalate

Hand off to the human expert via a signed web URL.

Arguments:

• conversationId (string, required)
• note (string, optional) — free-text context for the creator

Returns:

{
  "url": "https://proagentme.com/chat/<taskId>?escalate=1&t=<jwt>",
  "message": "To escalate to the human expert, open this URL…"
}

The URL is valid for 1 hour. The user opens it in a browser; payment and live chat happen in the web app.

search_marketplace

Public search — no auth required on the HTTP layer, but the MCP server still requires a valid bearer token (MCP auth wraps every call). Use when ask returns NO_AGENT_MATCH or you want to discover new agents.

Arguments:

• query (string, 1–200 chars, required)

Returns: same shape as list_my_agents.

Error shape

MCP errors follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32005,
    "message": "…",
    "data": { "code": "TASK_LIMIT" }
  }
}

The human-readable message is rendered verbatim by most MCP clients. The data.code is machine-readable — see Error codes.