Overview

Voyp MCP Server implements the Model Context Protocol (MCP) to provide secure, two-way integration between AI assistants and telephony services. It exposes a small set of MCP tools that let an assistant construct call contexts, initiate and control calls, and report call status — enabling AI models to make real-time phone calls, monitor progress, and hang up when appropriate.

Built to work as an MCP server for clients like Claude Desktop and Goose, Voyp bridges an AI model with Voyp’s telephony API. Developers can run the server locally (stdio) or connect to Voyp’s streamable endpoint, and authenticate requests with a Voyp API key or OAuth2 token.

Features

Two-way MCP integration: start calls and receive call state updates.
Context construction and business lookup for natural call workflows.
Call lifecycle controls: start, monitor, hang up.
Compatible with MCP clients (Claude Desktop, Goose, etc.).
Stream-capable HTTP endpoint for remote clients.
Simple configuration via environment variables or client config.

Installation / Configuration

Prerequisites:

Node.js v20+
Voyp API key (required to place and pay for calls)
MCP client (e.g., Claude Desktop, Goose)

Quick NPX run

# runs the server directly with NPX
npx -y voyp-mcp@latest

Install via Smithery (for Claude Desktop)

npx -y @smithery/cli install @paulotaylor/voyp-mcp --client claude

Git clone & build

git clone https://github.com/paulotaylor/voyp-mcp.git
cd voyp-mcp
npm install
npm run build
node build/index.js

Environment variables

VOYP_API_KEY=sk_your_voyp_key_here
PORT=3000         # optional, when running HTTP stream server

Claude Desktop configuration (macOS / Windows) Create or edit the Claude Desktop MCP servers configuration and add an entry that runs NPX or points to the built script. Replace the API key and the path as necessary.

Example (JSON):

{
  "mcpServers": {
    "voyp-mcp": {
      "command": "npx",
      "args": ["-y", "voyp-mcp"],
      "env": {
        "VOYP_API_KEY": "sk_your_voyp_key_here"
      }
    }
  }
}

Remote streamable endpoint Voyp provides an HTTP stream endpoint that can be used by remote MCP clients:

https://api.voyp.app/mcp/stream

Authenticate requests with an Authorization header:

Authorization: Bearer sk_your_voyp_key_here

Example curl:

curl -H "Authorization: Bearer sk_xyz" https://api.voyp.app/mcp/stream

Available Tools / Resources

The Voyp MCP server exposes a small, focused toolset for call workflows. Typical tools include:

start_call: Build call context and initiate a call (destination, caller id, script context).
hangup_call: Terminate an active call.
get_call_status: Query current call state and metadata.
search_business: Find businesses and returned contact numbers for context-building.
build_call_context: Helper to compose natural-language call scripts and metadata.

Repository and docs:

GitHub: https://github.com/paulotaylor/voyp-mcp

Environment variables (quick reference):

Variable	Purpose
VOYP_API_KEY	API key used to authenticate requests
PORT	Optional HTTP port for stream server

Use Cases

Restaurant reservation via assistant
- Assistant uses search_business to find nearby restaurants and fetch phone numbers.
- build_call_context composes a reservation script (date, time, party size).
- start_call initiates the call; get_call_status tracks progress and results; hangup_call ends the call.
Telehealth appointment scheduling
- Assistant composes patient info and appointment context.
- start_call dials the clinic, reads patient details or transfers to scheduling queue.
- Call logs and statuses are returned for audit and confirmation.
Automated verification or OTP via voice
- Backend triggers an assistant flow to call a user phone, read a verification code, and confirm response.
- get_call_status confirms delivery and whether the call was answered.
Contact-center augmentation
- AI agent can place calls, gather notes, and summarize outcomes back into CRM.
- Two-way integration lets the model adapt scripts based on real-time call state.

Notes and Best Practices

Security: keep VOYP_API_KEY secret and rotate keys as needed. Prefer OAuth tokens for multi-user deployments.
Costs: Voyp calls consume credits; ensure billing/credits are provisioned before heavy testing.
Local usage: running the server locally (stdio) is sufficient for development, but use the streamable endpoint for remote or production deployments.

For complete examples and the source code, see the project repository: https://github.com/paulotaylor/voyp-mcp.

Voyp MCP Server for Secure Two-Way Data Integration