Skip to content

MCP servers — overview

For the concept (what MCP is, how Vonzio uses it), read MCP servers first. This page is the reference for the specific endpoints.

ServerURLAuth
memory<INTERNAL>/mcp/memoryBearer mem_<…>
notify<INTERNAL>/mcp/notifyBearer notify_<…>
mail<INTERNAL>/mcp/mailBearer mail_<…>
calendar<INTERNAL>/mcp/calendarBearer calendar_<…>
vonzio (platform)<INTERNAL>/mcp/platformBearer platform_<…>

<INTERNAL> is the value of INTERNAL_SERVER_URL — http://server:3000 in the default Docker Compose install. Agent containers reach these via the Docker network, not the public internet.

The token in Authorization is minted by the orchestrator per task. It resolves server-side to the session/user/profile context — see MCP concept.

All MCP servers speak JSON-RPC 2.0 over HTTP POST. Methods you’ll see:

MethodPurpose
initializeHandshake. Returns server info + capabilities.
notifications/initializedClient-side ready signal. No-op on server.
tools/listReturns the array of { name, description, inputSchema } for tools.
tools/callCalls a tool. params: { name, arguments }.

For details consult the Model Context Protocol spec. Vonzio’s MCP servers stay strict-spec compliant.

When an MCP server is injected, the agent sees its tools prefixed mcp__<server>__<tool>. So notify_user from the notify server becomes mcp__notify__notify_user. This mirrors the standard MCP-in-Claude-Agent-SDK convention.

MCP tool calls return a content array with isError: true on the failure path:

{
"content": [{ "type": "text", "text": "Mail error: IMAP login failed" }],
"isError": true
}

The agent receives this as a tool result. Well-prompted agents either retry or surface the error to the user via notify_user.

You almost never call these endpoints directly — they expect the orchestrator-minted bearer tokens, which are short-lived in-memory. For testing in dev, you can spin a one-shot via the agent runtime: submit a task that calls the MCP tool you want to exercise.