voicegw mcp

Start the VoiceGateway MCP (Model Context Protocol) server.

Synopsis

The mcp command starts an MCP server that exposes 17 tools for AI coding agents to inspect and manage the gateway. Agents like Claude Code, Cursor, and Codex can use these tools to check provider status, view costs, register models, create projects, and more — all without leaving their workflow.

Usage

voicegw mcp [OPTIONS]

Options

Flag	Short	Type	Default	Description
`--transport`	`-t`	`string`	`stdio`	Transport layer: `stdio` for local agents, `http` for remote/SSE.
`--host`		`string`	`127.0.0.1`	HTTP bind host (only used with `--transport http`).
`--port`	`-p`	`integer`	`8090`	HTTP bind port (only used with `--transport http`).
`--config`	`-c`	`string`	`null`	Path to `voicegw.yaml`. Auto-discovered if omitted.

Prerequisites

The mcp extra must be installed:

pip install "voicegateway[dashboard]"
# or with uv
uv pip install "voicegateway[dashboard]"

For the HTTP transport, the dashboard extra is also needed (for uvicorn and starlette):

pip install "voicegateway[dashboard]"

Transport modes

stdio (default)

Used by local coding agents that launch the MCP server as a subprocess. The agent communicates over stdin/stdout using the MCP protocol.

voicegw mcp --transport stdio

No authentication is required for stdio transport.

HTTP/SSE

Used for remote access or shared team gateways. The server exposes an SSE endpoint at /sse and accepts messages at /messages/.

voicegw mcp --transport http --port 8090

Authentication is enabled by setting the VOICEGW_MCP_TOKEN environment variable. See MCP transports for details.

Examples

# Start with stdio for Claude Code (default transport)
voicegw mcp

# Start HTTP server for remote agents
VOICEGW_MCP_TOKEN=my-secret-token voicegw mcp --transport http --port 8090

# Start on a custom host and port
voicegw mcp -t http --host 0.0.0.0 --port 9000

# Use a specific config file
voicegw mcp --config /etc/voicegateway/voicegw.yaml

Available tools

The MCP server exposes 17 tools across four categories:

Category	Tools
Observability	`get_health`, `get_provider_status`, `get_costs`, `get_latency_stats`, `get_logs`
Providers	`list_providers`, `get_provider`, `test_provider`, `add_provider`, `delete_provider`
Models	`list_models`, `register_model`, `delete_model`
Projects	`list_projects`, `get_project`, `create_project`, `delete_project`

See the MCP tools reference for full documentation. voicegw serve | voicegw dashboard | voicegw status | MCP setup | MCP index

API

CLI

MCP server

Architecture

Help

Contributing

Synopsis

Usage

Options

Prerequisites

Transport modes

stdio (default)

HTTP/SSE

Examples

Available tools

​Synopsis

​Usage

​Options

​Prerequisites

​Transport modes

​stdio (default)

​HTTP/SSE

​Examples

​Available tools

​Related

Synopsis

Usage

Options

Prerequisites

Transport modes

stdio (default)

HTTP/SSE

Examples

Available tools

Related