Documentation

MCP server

Give Claude Desktop, Cursor, or any MCP-compatible AI agent a phone. The By Your Side MCP server exposes place_call, get_call, and list_calls as tool calls so your AI agent can place and track outbound calls without writing any API code.

Prerequisites

Node 18 or newer
A By Your Side agent API key (starts with bys_ak_). Create one under Account - Developers.
At least one phone number on your account.
The voip-agent repository cloned locally (the MCP server runs from source today; a published npm package is coming).

Running from source. The MCP server is not yet published to npm. Clone the repository, point your MCP client at the absolute path to mcp/src/server.js, and run npm install in the mcp/ directory first. An npm publish step is planned; this page will be updated when it ships.

Configure Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent path on your OS). Replace the path and API key with your own values.

claude_desktop_config.json

{
  "mcpServers": {
    "byourside": {
      "command": "node",
      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
      "env": {
        "BYOURSIDE_API_KEY": "bys_ak_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving. The byourside server appears in the tool list.

Configure Cursor

Add to .cursor/mcp.json in your project, or to the global ~/.cursor/mcp.json.

.cursor/mcp.json

{
  "mcpServers": {
    "byourside": {
      "command": "node",
      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
      "env": {
        "BYOURSIDE_API_KEY": "bys_ak_YOUR_KEY"
      }
    }
  }
}

Point at a staging instance

Add BYOURSIDE_API_BASE to the env block to target a staging or self-hosted API:

env block with custom base URL

"env": {
  "BYOURSIDE_API_KEY":  "bys_ak_YOUR_KEY",
  "BYOURSIDE_API_BASE": "https://staging.example.com"
}

Available tools

Tool	What it does
`place_call`	Places an outbound AI call. Inputs: `to` (required, E.164), `objective` (required), `context`, `fields`, `webhookUrl`, `callerId`. Returns `{ callId, status }`.
`get_call`	Fetches the current status and result of a call. Input: `callId` (required). Returns the full call record including `status`, `summary`, `transcript`, `extracted`, and `recordingUrl`. Poll this until status is terminal.
`list_calls`	Lists recent calls on your account (most recent first). Input: `limit` (optional, default 20, max 100). Returns `{ calls: [...] }`.

See the API reference for the full parameter and response field definitions.

Sample prompt

Once the MCP server is configured, you can instruct your AI agent in plain language:

Sample prompt for your AI agent

Place a call to +14155550123. The objective is:
"Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule."
Extract two fields: confirmed (boolean) and new_time (string).
Then poll get_call every 10 seconds until the status is terminal and show me the result.

Verify it is working

Check your keyMake sure BYOURSIDE_API_KEY is set to a valid bys_ak_ key. The server exits with a non-zero code immediately if the key is missing.
Ask your agent to place a test callUse a number you control. Give a short, concrete objective and one boolean extraction field (e.g. { name: "confirmed", type: "boolean" }).
Poll for the resultAsk your agent to call get_call with the returned callId until the status is terminal. Verify that extracted.confirmed is present.
Test a blocked destinationAsk your agent to call a premium-rate number and confirm the destination_blocked error is returned.