Vonage API MCP server

Available Tools

This MCP server provides access to various Vonage API functionalities through the following tools:

Usage Examples

Check Account Balance

Can you check my Vonage account balance?

List Your Phone Numbers

Can you list out the numbers that I own for Vonage?

Search for Available Numbers to Purchase

Can you search for available Vonage numbers to purchase in the US?

Or search with specific criteria:

Can you search for available Vonage numbers in the US with SMS and VOICE features?

Can you search for available numbers in GB starting with pattern "44207*"?

List Applications

Can you list out the applications on my account?

Create a New Application

Can you create a new Vonage application called "My Chat App"?

Or let the system suggest a name:

Can you create a new Vonage application?

Get a Records Report

Query by date range:

Can you get a report of all outbound SMS sent over the last week?

Query by specific ID:

Can you get the report for Voice Call ID 1234-abcd-5678-efgh?

Send an SMS

Can you send an SMS to +1234567890 with the message "Hello from Vonage!"?

Send a WhatsApp Message

Can you send a WhatsApp message to +1234567890 with the message "Hello from Vonage over WhatsApp!"?

Send a WhatsApp Message with SMS Failover

Can you send a WhatsApp message with SMS failover to +1234567890 saying "Hello from Vonage with failover!"?

Send an RCS Message

Can you send an RCS message to +1234567890 with the message "Hello from Vonage via RCS!"?

Send an RCS Message with SMS Failover

Can you send an RCS message with SMS failover to +1234567890 saying "Hello from Vonage RCS with fallback!"?

Generate a Chart

Please create a chart showing all the outbound SMS sent over the last week.

Related MCP server: Telnyx MCP Server

Set up the MCP server

• VS Code

• Cursor

• Windsurf

• Claude Desktop

The details of the MCP server should look like this.

"vonage-mcp-server-api-bindings": {
    "type": "stdio",
    "command": "npx",
    "args": [
        "-y",
        "@vonage/vonage-mcp-server-api-bindings"
    ],
    "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_PRIVATE_KEY64": "<YOUR_VONAGE_PRIVATE_KEY64>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_API_SECRET": "<YOUR_VONAGE_API_SECRET>",
        "VONAGE_VIRTUAL_NUMBER": "<YOUR_VONAGE_VIRTUAL_NUMBER>",
        "VONAGE_WHATSAPP_NUMBER": "<YOUR_VONAGE_WHATSAPP_NUMBER>",
        "RCS_SENDER_ID": "<YOUR_RCS_SENDER_ID>"
    }
}

Encoding your private key

VONAGE_PRIVATE_KEY64 must be your application's private key file, base64 encoded on a single line. Run one of these commands locally, replacing private.key with the path to your key file, and paste the output into your config:

macOS:

base64 -i private.key

Linux:

base64 -w 0 private.key

Windows PowerShell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path .\private.key)))

Security

STDIO transport

This server runs locally and talks to your MCP client (VS Code, Cursor, Claude Desktop, etc.) over STDIO. Tool calls and their responses travel between the two processes as plaintext JSON-RPC. There is no transport-layer encryption or authentication on this channel, which is how local MCP servers are designed to work.

That is safe on a single-user machine you trust, which is the intended way to run this server. Keep in mind that:

• Any process with enough privilege on the same machine can read or tamper with the STDIO stream. If the machine is compromised, the server cannot protect the data passing through it.

• In shared, multi-user, or containerised environments, other users or workloads may be able to observe the process. Only run the server where you trust everything else running alongside it.

Storing credentials

The setup above puts your Vonage credentials, including VONAGE_PRIVATE_KEY64, into your MCP client's config file (for example claude_desktop_config.json or .cursor/mcp.json) as plaintext. Any process running as your user can read that file, and it is easy to leak by accident.

• Treat VONAGE_PRIVATE_KEY64 like a private SSH key. Anyone who has it can act as your Vonage application.

• If the config file lives inside a project, such as .cursor/mcp.json or .vscode/mcp.json, add it to that project's .gitignore so it is never committed.

• Cloud sync services (iCloud, Dropbox, OneDrive, Google Drive) can silently upload config directories. Exclude those directories from sync, or keep credential-bearing config files outside synced folders.

• For stronger protection, keep the secrets out of the config file entirely. The options are below.

Keeping secrets out of the config file

The server only reads credentials from its environment, so the goal is to have your MCP client supply VONAGE_PRIVATE_KEY64 and VONAGE_API_SECRET at launch without writing them into a file. This protects the credentials at rest. Once the server is running, they are still in its environment.

macOS (Keychain)

Store the secrets in your login Keychain. The private key is too long to paste at a terminal prompt, so the first command reads it straight from the key file. The second command ends with -w, which makes security prompt for the API secret so it doesn't end up in your shell history:

security add-generic-password -a "$USER" -s vonage-mcp-private-key64 -w "$(base64 -i private.key)"
security add-generic-password -a "$USER" -s vonage-mcp-api-secret -w

Then launch the server through a shell that reads them from Keychain, and keep only the non-secret values in env:

"vonage-mcp-server-api-bindings": {
    "type": "stdio",
    "command": "/bin/sh",
    "args": [
        "-c",
        "VONAGE_PRIVATE_KEY64=$(security find-generic-password -s vonage-mcp-private-key64 -w) || exit 1; VONAGE_API_SECRET=$(security find-generic-password -s vonage-mcp-api-secret -w) || exit 1; export VONAGE_PRIVATE_KEY64 VONAGE_API_SECRET; exec npx -y @vonage/vonage-mcp-server-api-bindings"
    ],
    "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_VIRTUAL_NUMBER": "<YOUR_VONAGE_VIRTUAL_NUMBER>",
        "VONAGE_WHATSAPP_NUMBER": "<YOUR_VONAGE_WHATSAPP_NUMBER>",
        "RCS_SENDER_ID": "<YOUR_RCS_SENDER_ID>"
    }
}

The first time the server starts, macOS may ask whether security can access the items. Choose Always Allow so later launches don't prompt.

VS Code (input variables)

VS Code can prompt for a secret the first time the server starts and store it securely, using input variables in .vscode/mcp.json or your user-profile mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "vonage-private-key64",
      "description": "Vonage private key (base64)",
      "password": true
    },
    {
      "type": "promptString",
      "id": "vonage-api-secret",
      "description": "Vonage API secret",
      "password": true
    }
  ],
  "servers": {
    "vonage-mcp-server-api-bindings": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vonage/vonage-mcp-server-api-bindings"],
      "env": {
        "VONAGE_APPLICATION_ID": "<YOUR_VONAGE_APPLICATION_ID>",
        "VONAGE_API_KEY": "<YOUR_VONAGE_API_KEY>",
        "VONAGE_PRIVATE_KEY64": "${input:vonage-private-key64}",
        "VONAGE_API_SECRET": "${input:vonage-api-secret}"
      }
    }
  }
}

Add the remaining non-secret variables from the setup example to env as needed. VS Code doesn't forward servers that use input variables to Copilot harness sessions. See the VS Code MCP configuration reference for details.

Linux and Windows

Neither has a secret store with a command-line client that is installed and working by default. If you already use one, such as secret-tool with GNOME Keyring or PowerShell SecretManagement, you can apply the same pattern as the macOS example: launch the server through a shell that reads the secrets and exports them before starting it. Otherwise, follow the file-handling guidance above.