> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicegateway.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# voicegw mcp

> Start the VoiceGateway MCP (Model Context Protocol) server so coding agents can inspect and manage the gateway.

# voicegw mcp

Start the VoiceGateway MCP (Model Context Protocol) server.

## Purpose

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.

## Syntax

```bash theme={null}
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:

```bash theme={null}
pip install "voicegateway[mcp]"
```

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

```bash theme={null}
pip install "voicegateway[mcp,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.

```bash theme={null}
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/`.

```bash theme={null}
voicegw mcp --transport http --port 8090
```

Authentication is enabled by setting the `VOICEGW_MCP_TOKEN` environment variable. See [MCP Authentication](/mcp/authentication) for details.

## Examples

### Start with stdio for Claude Code

```bash theme={null}
voicegw mcp
```

Claude Code would be configured to launch this command as its MCP server.

### Start HTTP server for remote agents

```bash theme={null}
VOICEGW_MCP_TOKEN=my-secret-token voicegw mcp --transport http --port 8090
```

### Start on a custom host and port

```bash theme={null}
voicegw mcp -t http --host 0.0.0.0 --port 9000
```

### Use a specific config file

```bash theme={null}
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](/mcp/tools/observability) for full documentation.

## Related Commands

* [`voicegw serve`](/cli/serve) -- the HTTP API (MCP is a separate server)
* [`voicegw dashboard`](/cli/dashboard) -- the web UI
* [`voicegw status`](/cli/status) -- quick status check before starting MCP