Documentation

MCP server

Give Claude, 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.

There are two ways to connect. The hosted connector is the easiest and is recommended for most people: nothing to install, just add a URL and paste your key. If you prefer to keep everything on your own machine, you can run it locally instead.

Recommended: hosted connector

By Your Side runs the MCP server for you. You add it to Claude as a remote connector and authorize it with your agent API key. There is nothing to install or keep running.

Open the connector settings in ClaudeGo to Settings - Connectors and press Add custom connector.
Enter a name and the server URLGive it any name (for example By Your Side). For the remote MCP server URL, enter the address below. The /mcp path matters, so include it.
Remote MCP server URL
```
https://mcp.byourside.ai/mcp
```
Leave the Advanced OAuth Client ID and Client Secret fields blank.
Add the connectorPress Add. Claude opens a By Your Side approval screen.
Authorize with your agent keyPaste an agent API key (a bys_ak_ key from the Developers page) and press Approve and connect.
Ask Claude to place a callUse plain language. Claude uses the place_call, get_call, and list_calls tools automatically.
Sample prompt
```
Call +14155550123 and ask if they are open on Sunday,
then tell me what they said.
```

Your key stays with us. Your agent API key is stored on the By Your Side server. Claude only receives a connection token, never the key itself. To disconnect, remove the connector in Claude or revoke the key on the Developers page.

The hosted connector works with any MCP client that supports remote servers with OAuth, not only Claude.

Run it locally instead

Prefer to keep the key and the server on your own machine? Run the published byourside-mcp package as a local (stdio) server from your MCP client. You will need Node 18 or newer and an agent API key (a bys_ak_ key from the Developers page).

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 API key with your own value.

claude_desktop_config.json

{
  "mcpServers": {
    "byourside": {
      "command": "npx",
      "args": ["-y", "byourside-mcp"],
      "env": {
        "BYOURSIDE_API_KEY": "bys_ak_YOUR_KEY"
      }
    }
  }
}

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

Configure Cursor

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

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 toward an objective. 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 by `callId` (required). Returns the full call record including `status`, `summary`, `transcript`, `extracted` fields, 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 connector is in place, you can instruct your AI agent in plain language. A more detailed example:

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

Confirm the connectionFor the hosted connector, make sure the By Your Side connector shows as connected in Claude. For a local setup, make sure BYOURSIDE_API_KEY is set to a valid bys_ak_ key (the local server exits 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.