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.
Endpoints
Section titled “Endpoints”| Server | URL | Auth |
|---|---|---|
memory | <INTERNAL>/mcp/memory | Bearer mem_<…> |
notify | <INTERNAL>/mcp/notify | Bearer notify_<…> |
mail | <INTERNAL>/mcp/mail | Bearer mail_<…> |
calendar | <INTERNAL>/mcp/calendar | Bearer calendar_<…> |
vonzio (platform) | <INTERNAL>/mcp/platform | Bearer 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.
Wire format
Section titled “Wire format”All MCP servers speak JSON-RPC 2.0 over HTTP POST. Methods you’ll see:
| Method | Purpose |
|---|---|
initialize | Handshake. Returns server info + capabilities. |
notifications/initialized | Client-side ready signal. No-op on server. |
tools/list | Returns the array of { name, description, inputSchema } for tools. |
tools/call | Calls a tool. params: { name, arguments }. |
For details consult the Model Context Protocol spec. Vonzio’s MCP servers stay strict-spec compliant.
Tool naming in agents
Section titled “Tool naming in agents”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.
When a tool fails
Section titled “When a tool fails”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.
Direct calls (debugging)
Section titled “Direct calls (debugging)”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.