> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Give your AI agent a phone: connect Claude, Cursor, or any MCP client to LumisReach over Streamable HTTP.

LumisReach runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. Point any
MCP client at it with an API key and your agent can place AI phone calls, run AI text conversations,
buy numbers, and read call history — no SDK, no local process to run.

## Endpoint

|                    |                                        |
| ------------------ | -------------------------------------- |
| **MCP endpoint**   | `https://mcp.lumisreach.com/mcp`       |
| **Transport**      | Streamable HTTP                        |
| **Authentication** | `Authorization: Bearer <your API key>` |
| **REST API base**  | `https://api.lumisreach.com/api/v1`    |

Every tool is a thin wrapper over the v1 REST API using your own key, so scopes, rate limits and
tenant isolation behave exactly as they do for a direct HTTP call.

## Access requirements

<Steps>
  <Step title="A LumisReach account">
    Sign in at [app.lumisreach.com](https://app.lumisreach.com). Your workspace is what the agent acts inside
    — calls, contacts and transcripts land there.
  </Step>

  <Step title="An API key">
    **Settings → Developer API** ([app.lumisreach.com/settings/api](https://app.lumisreach.com/settings/api)).
    The key is shown once; store it somewhere safe. A key created this way is unrestricted and works on every
    tool below.
  </Step>

  <Step title="A payment method for paid actions">
    Reading data is free. Placing calls, sending texts and buying numbers draw on your wallet, so add a card
    under **Settings → Billing** first. See [pricing](/api-reference/quick-agent-actions#pricing).
  </Step>
</Steps>

<Note>
  Nothing else is required to use the shared senders: quick calls and quick texts go out from LumisReach-owned
  numbers, so an agent can make its first call minutes after the key is created.
</Note>

## Connect a client

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http lumisreach https://mcp.lumisreach.com/mcp \
    --header "Authorization: Bearer $LUMISREACH_API_KEY"
  ```

  ```json Claude Desktop / generic theme={null}
  {
    "mcpServers": {
      "lumisreach": {
        "type": "http",
        "url": "https://mcp.lumisreach.com/mcp",
        "headers": {
          "Authorization": "Bearer lumisreach_your_api_key_here"
        }
      }
    }
  }
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "lumisreach": {
        "url": "https://mcp.lumisreach.com/mcp",
        "headers": {
          "Authorization": "Bearer lumisreach_your_api_key_here"
        }
      }
    }
  }
  ```
</CodeGroup>

## Tools

### Quick Agent Actions

These need no phone number of your own — they run from shared LumisReach senders. This is what an
agent should reach for by default.

| Tool                         | What it does                                                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `start_ai_phone_call`        | Call one or more numbers and hold a real conversation toward a goal, with automatic retries. $0.20 per call placed + $0.20/minute. |
| `start_ai_text_conversation` | Open an SMS thread and keep answering replies until the goal is met. \$0.05 per outbound message.                                  |
| `get_quick_action_status`    | Per-number progress for a call or text job: attempts, live call state, messages, outcome.                                          |
| `cancel_quick_action`        | Stop remaining dials and AI replies for a job.                                                                                     |
| `setup_ai_phone_number`      | Buy a number **and** configure the AI agent that answers its calls (and optionally its texts). \$5/month.                          |
| `get_ai_phone_number_status` | Whether a number is still provisioning or ready to answer.                                                                         |

### Primitives

For callers that already own a number and want to drive it directly.

| Tool                                            | What it does                                                |
| ----------------------------------------------- | ----------------------------------------------------------- |
| `send_sms`                                      | Send one plain SMS from a number you own.                   |
| `place_call`                                    | Place a bridged outbound call from a number you own.        |
| `list_calls` / `get_call`                       | Call history and per-call detail.                           |
| `hangup_call`                                   | End an in-progress call.                                    |
| `list_phone_numbers`                            | The numbers your account owns.                              |
| `search_available_numbers` / `buy_phone_number` | Find and purchase a number without configuring an agent.    |
| `list_caller_ids`                               | Verified caller IDs and their CNAM display names.           |
| `get_usage`                                     | Current-month usage: calls, minutes, active numbers, spend. |

## Example

> "Call +1 415 555 0123 and find out whether they still want the quote. Try twice if nobody answers."

The agent calls `start_ai_phone_call` with the goal and `retry_attempts: 1`, gets back a job id, and
polls `get_quick_action_status` until the target reports `completed` with a summary of what was said.

## Troubleshooting

| Symptom                          | Cause                                                                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 unauthorized` on connect    | The key is missing, mistyped, expired, or revoked. Issue a new one under Settings → Developer API.                                                          |
| `409` mentioning a shared number | The shared pool is unavailable, out of daily volume, or shared SMS is not enabled here. Retry tomorrow or buy your own number with `setup_ai_phone_number`. |
| `402 payment_required`           | No payment method on file. Add one under Settings → Billing.                                                                                                |
| Calls place but nothing happens  | Check `get_quick_action_status` — `end_reason` carries the carrier's reason for the last attempt.                                                           |