Claude Code Integration

VoiceGateway includes an MCP (Model Context Protocol) server that lets you manage providers, models, projects, and monitor costs directly from Claude Code using natural language.

Setup

1. Install the MCP Extra

pip install voicegateway[mcp]

2. Configure Claude Code

Add VoiceGateway to your Claude Code MCP settings (~/.claude/settings.json or your project's .mcp.json):

{
  "mcpServers": {
    "voicegateway": {
      "command": "voicegw",
      "args": ["mcp"],
      "env": {
        "VOICEGW_CONFIG": "/path/to/voicegw.yaml"
      }
    }
  }
}

3. Verify the Connection

Start Claude Code and ask it to check VoiceGateway status. The MCP server exposes 17 tools across four categories: providers, models, projects, and observability.

Prompt Examples

1. Check System Status

Prompt:

What providers are configured in VoiceGateway? Show me the status of each one.

Claude Code will call the list_providers tool and display all configured providers, their types (cloud vs. local), and whether they have valid credentials (API keys are shown masked, e.g., sk-p...z789).

2. Add a New Provider

Prompt:

Add a Groq provider to VoiceGateway with API key "gsk_abc123xyz789".
Then register the llama-3.3-70b-versatile model as an LLM.

Claude Code will:

1. Call create_provider with provider_id="groq", provider_type="groq", and the API key
2. Call register_model with model_id="groq/llama-3.3-70b-versatile", modality="llm", provider_id="groq"
3. The API key is encrypted with Fernet before storage
4. Both actions are recorded in the audit log

3. Create a Project with Budget

Prompt:

Create a new project called "customer-support" with a $25 daily budget.
Set it to throttle mode so it falls back to local models when the budget is exceeded.
Tag it as "production" and "support".

Claude Code will call create_project with:

• project_id: "customer-support"
• name: "Customer Support"
• daily_budget: 25.00
• budget_action: "throttle"
• tags: ["production", "support"]

4. Monitor Costs

Prompt:

Show me today's costs broken down by project and provider.
Which model is costing us the most?

Claude Code will call the get_costs tool with period="today" and present the results as a structured breakdown. It will also call get_cost_by_project to show per-project spending and identify the most expensive model.

5. View Recent Requests and Latency

Prompt:

Show me the last 20 requests to VoiceGateway. Are there any with high latency or errors?
Flag any requests where TTFB exceeded 500ms.

Claude Code will call get_recent_requests with limit=20 and analyze the results, highlighting:

• Requests with status: "error"
• Requests where ttfb_ms > 500
• Any fallback events (fallback_from is not null)

6. Audit Configuration Changes

Prompt:

Show me all configuration changes made to VoiceGateway in the last 24 hours.
Who added or modified providers?

Claude Code will call get_audit_log and display the history of changes, including:

• What was changed (provider, model, or project)
• What action was taken (create, update, delete)
• The source of the change (api, mcp, dashboard)
• What specifically changed (from the changes_json field)

7. Delete Unused Resources

Prompt:

List all models registered in VoiceGateway. Delete the ones that have had zero requests in the last 30 days.

Claude Code will:

1. Call list_models to get all registered models
2. Call get_costs with period="month" to check usage
3. Identify models with zero requests
4. Call delete_model for each unused model (after confirming with you)

Available MCP Tools

Provider Tools

Model Tools

Project Tools

Observability Tools

Authentication

The MCP server supports API key authentication. Set the VOICEGW_MCP_API_KEY environment variable to require authentication for all MCP tool calls:

{
  "mcpServers": {
    "voicegateway": {
      "command": "voicegw",
      "args": ["mcp"],
      "env": {
        "VOICEGW_CONFIG": "/path/to/voicegw.yaml",
        "VOICEGW_MCP_API_KEY": "your-secret-key"
      }
    }
  }
}

End-to-End Workflow

Here is a complete workflow you can run through Claude Code:

1. "Show me what providers are configured in VoiceGateway."
2. "Add an ElevenLabs provider with API key 'xi_abc123'."
3. "Register the eleven_turbo_v2_5 model as a TTS model for ElevenLabs."
4. "Create a project called 'demo' with a $5 daily budget in warn mode."
5. "Show me today's costs and recent requests for the demo project."
6. "Show me the audit log -- what changes did we just make?"

Each step uses the MCP tools transparently. All API keys are encrypted at rest, changes are audit-logged, and the Gateway's config is automatically refreshed after each write.