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

Server	URL	Auth
`memory`	`<INTERNAL>/mcp/memory`	`Bearer mem_<…>`
`notify`	`<INTERNAL>/mcp/notify`	`Bearer notify_<…>`
`gmail`	`<INTERNAL>/mcp/gmail`	`Bearer gmail_<…>`
`teller`	`<INTERNAL>/mcp/teller`	`Bearer teller_<…>`
`vonzio` (platform)	`<INTERNAL>/mcp/platform`	`Bearer platform_<…>`

<INTERNAL> is the value of INTERNAL_SERVER_URL — http://server:3000 in dev, the in-cluster address in prod. 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

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

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

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

{
  "content": [{ "type": "text", "text": "Gmail authentication error: refresh token revoked" }],
  "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)

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.