mcp-vapi-generic-caller: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server that lets Claude make AI-powered outbound phone calls via Vapi. This server handles any type of call — customer service, sales, surveys, scheduling, etc. — in any language.

Single-file Python server (server.py) exposing two MCP tools: make_call (initiates call) and get_call_result (polls for outcome).

Commands

uv sync                      # Install dependencies
uv run python server.py      # Run MCP server (stdio transport)

# Or run directly (PEP 723 inline metadata):
uv run --script server.py

# Docker (for HTTP/cloud deployments only)
docker build -t mcp-vapi-caller .
docker compose up

No test suite or linter is configured.

MCP Server Registration

This server is registered in both Claude Code and Claude Desktop via a bash wrapper that sources secrets from a centralized env file:

{
  "command": "/bin/bash",
  "args": ["-c", "set -a; source ~/.config/mcp/secrets.env; set +a; exec /opt/homebrew/bin/uv run --directory /path/to/mcp-vapi-generic-caller python server.py"]
}

• Secrets file: ~/.config/mcp/secrets.env (chmod 600)
• Why wrapper: Claude Desktop is an Electron app that doesn't inherit shell env vars; the wrapper sources secrets at runtime

Architecture

Single-file design — all logic lives in server.py:

• MCP layer: Uses mcp[cli] / FastMCP to expose tools over stdio
• Vapi integration: Builds call payloads with a voice-optimized system prompt, sends them to api.vapi.ai, and parses results
• Prompt assembly: _build_system_prompt composes a prompt from building blocks (goal, script, language rules, voice style). The caller provides the domain-specific content; the server adds voice-conversation best practices.
• Language support: LANGUAGE_CONFIG dict provides per-language end-call phrases, goodbye rules, language enforcement, and voice style instructions (fr, en, es, de, it, pt)
• Structured extraction: Optional — the calling LLM provides a JSON Schema via structured_data_schema. If omitted, the call still returns transcript + summary.
• Call flow: make_call → POST to Vapi → returns call_id → get_call_result polls GET until call ends → returns structured data + transcript + recording URLs