byourside-mcp

MCP server that gives any MCP client (Claude Desktop, Cursor, etc.) a phone -- place outbound AI calls, poll for results, and list call history via the By Your Side Agent API.

Prerequisites

• Node 18 or newer
• A By Your Side agent API key (starts with bys_ak_)

Quick start

cd mcp
npm install
BYOURSIDE_API_KEY=bys_ak_your_key_here npm start

MCP client configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

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

Cursor

Add to .cursor/mcp.json in your project (or the global ~/.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_here" }
    }
  }
}

To point at a staging or self-hosted instance, add "BYOURSIDE_API_BASE": "https://staging.example.com" to the env block.

Tools

place_call

Places an outbound AI phone call toward an objective. Returns a callId immediately; the call runs asynchronously. Poll get_call with that callId until status is terminal.

Inputs:

| Field | Type | Required | Description | |---|---|---|---| | to | string | yes | Destination number in E.164 (e.g. +14155550123) | | objective | string | yes | What the call should accomplish | | context | string | no | Background context for the assistant | | fields | array | no | Structured fields to extract (up to 20 items: { name, type?, description? }) | | webhookUrl | string | no | HTTPS URL to receive the signed result when the call ends | | callerId | string | no | Caller ID override; must be a number on your account |

Returns: { callId, status } where status is queued on success.

get_call

Fetches the current status and result of a call.

Inputs:

| Field | Type | Required | Description | |---|---|---|---| | callId | string | yes | The callId from place_call |

Returns: { id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }

list_calls

Lists recent calls placed by your account (most recent first).

Inputs:

| Field | Type | Required | Description | |---|---|---|---| | limit | number | no | Max calls to return (default 20, max 100) |

Returns: { calls: [ { id, to, objective, status, summary, createdAt, startedAt, endedAt, durationSec, error? } ] }

Call statuses

| Status | Terminal? | Meaning | |---|---|---| | queued | no | Call accepted, not yet dialing | | ringing | no | Dialing the destination | | in_progress | no | Call is live | | completed | yes | Call finished normally | | no_answer | yes | Destination did not pick up | | voicemail | yes | Reached voicemail | | declined | yes | Call was rejected | | failed | yes | Technical failure |

Place your first call

1. Configure your MCP client as above.
2. Ask your assistant: "Place a call to +14155550123 with the objective: confirm the meeting time for tomorrow at 2pm."
3. The assistant calls place_call and gets back a callId.
4. Ask: "Check on call <callId> -- did it complete?"
5. The assistant calls get_call and returns the status, summary, and any extracted fields.

Manual end-to-end test

1. Set BYOURSIDE_API_KEY and optionally BYOURSIDE_API_BASE in your MCP client config.
2. Configure the client using the JSON above.
3. Ask your agent to call a number you control with a specific objective and one extraction field (e.g. { name: "confirmed", type: "boolean" }).
4. Confirm place_call returns a callId.
5. Call get_call repeatedly until status is terminal; verify extracted.confirmed is present.
6. Try a blocked destination (e.g. a premium-rate number) and confirm the mapped error message is returned.

Development

Run tests:

cd mcp && node --test

Check server parses:

node --check mcp/src/server.js

Smoke test (missing key, should exit 1):

node mcp/src/server.js

Smoke test (with dummy key, should print "ready on stdio" to stderr):

BYOURSIDE_API_KEY=bys_ak_test node mcp/src/server.js