Agent Setup

Prerequisites

pip install "voicegateway[dashboard,livekit]"

uv add "voicegateway[dashboard,livekit]"

The MCP server ships inside the dashboard extra; there is no separate mcp extra. livekit is required too, even for Pipecat-only agents: every voicegw subcommand imports it at CLI startup. See Installation for the full extras matrix.

Claude Code

Add to .mcp.json in your project root, or your user-scoped Claude config:

{
  "mcpServers": {
    "voicegateway": {
      "command": "voicegw",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

With a non-default config file:

{
  "mcpServers": {
    "voicegateway": {
      "command": "voicegw",
      "args": ["mcp", "--transport", "stdio", "--config", "/path/to/voicegw.yaml"]
    }
  }
}

If VoiceGateway is installed in a virtualenv that isn’t on PATH, point command at the full binary path instead (e.g. /path/to/venv/bin/voicegw). Restart Claude Code after saving. It connects over stdio and lists the ten default tools (25 with VOICEGW_MCP_ADMIN=1 set on the server). See Default tools.

Cursor

Add the same command/args shape to .cursor/mcp.json (project) or the global Cursor MCP settings for stdio, or point at a shared HTTP/SSE server:

{
  "mcpServers": {
    "voicegateway": {
      "url": "http://your-server:8090/sse",
      "headers": { "Authorization": "Bearer your-token-here" }
    }
  }
}

See Transports & auth for running the server that way and securing it.

Codex (OpenAI CLI)

Codex speaks MCP over stdio with the same config shape as Claude Code above.

Example prompts

Against the default tool surface (VOICEGW_MCP_ADMIN unset):

Prompt	Tool called
”Check VoiceGateway health”	`get_health`
”What’s tonys-pizza spending this week?”	`get_costs` with `period="week", project="tonys-pizza"`
”Create a project called demo with a $5 daily budget”	`create_project`
”Show me the last 20 errors”	`get_logs` with `status="error", limit=20`
”What models can I route to?”	`list_models`

With VOICEGW_MCP_ADMIN=1 the agent can also add and test provider credentials and delete resources; see Admin tools.

Next steps

Transports & auth: stdio vs. HTTP/SSE, and securing the HTTP transport.
CLI reference: mcp: all flags for voicegw mcp.

API

CLI

MCP server

Architecture

Help

Contributing

Prerequisites

Claude Code

Cursor

Codex (OpenAI CLI)

Example prompts

Next steps

​Prerequisites

​Claude Code

​Cursor

​Codex (OpenAI CLI)

​Example prompts

​Next steps

Prerequisites

Claude Code

Cursor

Codex (OpenAI CLI)

Example prompts

Next steps