---
title: "MCP server reference"
description: "Every CallForMe MCP tool, argument and return shape, plus how OAuth connect works: place_call, get_call, answer_question, share_call, find_business and more."
url: https://callforme.tel/docs/mcp
updated: 2026-09-29
---

# MCP server reference

> CallForMe is a remote MCP server over streamable HTTP at https://callforme.tel/mcp with standard OAuth sign-in. Adding it shows a Connect step that creates your account in one click. It has ten tools, including place_call, get_call, answer_question and share_call. Clients without OAuth can use /mcp/open or a personal key URL.

## Endpoint

```
https://callforme.tel/mcp
```

Remote MCP, streamable HTTP, stateless, with standard MCP authorization (OAuth).

## Connecting

When you add the URL, your client shows a Connect, Authenticate or Sign in step. A browser tab opens and closes by itself. There's no email, no form and no card. That creates your CallForMe account, and the client keeps the token for every later session.

The only other step is one setup link, the first time your agent places a real call, to add $10. After that every chat just calls. A second agent's first link recognizes you and links it to the same account in one click. See [how setup links work](/docs/setup-links).

### Clients without OAuth

| Endpoint | Auth | Behavior |
|---|---|---|
| `https://callforme.tel/mcp` | OAuth | The default. One click to connect. |
| `https://callforme.tel/mcp/open` | None | Works anywhere. Your agent gets a setup link in each new session unless it saves the `account_key` it receives and passes it back. |
| `https://callforme.tel/mcp/k/<your key>` | Key in the URL | Create a key on the [account page](https://callforme.tel/account). Calls go straight to your account. |
| `https://callforme.tel/mcp` + header | `Authorization: Bearer cfm_...` | Same key, sent as a header instead of in the URL. |

On any endpoint, `place_call` also accepts `"account_key": "cfm_..."` and `"setup_code": "k7m2q"` (after the user finishes a setup link).

## Tools

| Tool | Arguments | Account | Returns |
|---|---|---|---|
| `place_call` | `phone` (required), `goal` (required), `business_name`, `details`, `questions`, `on_behalf_of`, `callback_number`, `constraints`, `voicemail_message`, `transfer_to`, `language`, `setup_code`, `account_key` | Balance needed to dial (demo line is free) | `calling`, `needs_setup`, or `blocked` |
| `get_call` | `call_id`, `wait_seconds` (0 to 50) | Yes | Status, transcript, pending question, answers, outcome, duration, cost |
| `answer_question` | `call_id`, `answer` | Yes | Confirms the answer was passed to the voice assistant |
| `hang_up` | `call_id` | Yes | Ends the call |
| `plan_call` | Same as `place_call` without `setup_code` and `account_key` | No | Opening line, checklist, likely uncovered questions, open-now check, cost estimate |
| `find_business` | `query`, `near` | No | Name, phone, address, open now, hours today, rating |
| `share_call` | `call_id`, `public` (default `true`) | Yes | A public link at `https://callforme.tel/c/<id>`. Pass `public: false` to turn it off. |
| `list_calls` | `limit` | Yes | Your recent calls |
| `account` | none | Yes | Balance, auto-reload setting, top-up link |
| `pricing` | none | No | Current prices |

`place_call` to the demo line, Maple Street Pizza at +1 469 770 7412 (a fictional restaurant), needs no payment: up to 5 free calls a day per user.

There's also a `get_setup` helper for the setup flow: after the user finishes a setup link, your agent can call it with the code instead of passing `setup_code` to `place_call` again. See [setup links](/docs/setup-links).

### place_call arguments

| Argument | Type | Notes |
|---|---|---|
| `phone` | string | Required. US or Canadian number. E.164 (`+19725550100`) is safest. |
| `goal` | string | Required. One sentence with the outcome you want. |
| `business_name` | string | Used in the call and in results. |
| `details` | string | Facts the assistant may share: names, order numbers, car model. |
| `questions` | string[] | What you want answered. Each comes back in `answers`. |
| `on_behalf_of` | string | The requester's name. Used in the opener. |
| `callback_number` | string | A number the business can use to reach the requester. |
| `constraints` | string | Limits, like "don't agree to more than $200". |
| `voicemail_message` | string | Left only if the call reaches voicemail. Without it, the assistant hangs up on voicemail. |
| `transfer_to` | string | The requester's phone. They're patched in when a human answers. |
| `language` | string | Defaults to `en`. |
| `setup_code` | string | From a `needs_setup` response, after the user finishes the link. |
| `account_key` | string | A `cfm_` key, if not sent another way. |

### place_call responses

```json
{ "status": "calling", "call_id": "call_8f2k1" }
```

```json
{
  "status": "needs_setup",
  "setup_url": "https://callforme.tel/go/k7m2q",
  "setup_code": "k7m2q",
  "message_for_user": "To place this call, open https://callforme.tel/go/k7m2q and add $10. Then tell me when you're done."
}
```

```json
{ "status": "blocked", "reason": "This number has asked not to receive automated calls." }
```

On `/mcp/open`, the first successful `place_call` after setup also includes `account_key` (`cfm_...`), shown once. Save it. OAuth and personal-key connections don't need to.

### get_call response

```json
{
  "status": "ended",
  "transcript": [
    { "role": "business", "text": "Nonna's, this is Kate." },
    { "role": "assistant", "text": "Hi Kate, I'm an automated assistant calling on behalf of Jordan..." }
  ],
  "pending_question": null,
  "answers": {
    "Is there a booth?": "No, window table instead."
  },
  "outcome": {
    "success": true,
    "summary": "Booked 4 at 7:45pm Friday under Jordan.",
    "confirmation_number": null,
    "price_quoted": null,
    "appointment_time": "Friday 7:45pm",
    "next_steps": "None."
  },
  "duration_s": 58,
  "cost_usd": 1.00
}
```

`status` moves through `queued`, `ringing`, `in_progress`, `ended`. The transcript shape above is illustrative; the fields listed in this section are the contract.

### Mid-call questions

When the business asks something the assistant doesn't know, `get_call` returns a `pending_question` string. Reply with:

```json
{ "call_id": "call_8f2k1", "answer": "Use 469-555-0199." }
```

on `answer_question`. The assistant waits on the line up to about 60 seconds. If there's no answer within about 50 seconds, it tells the business it'll call back.

### Sharing a call

`share_call` makes a read-only page for one ended call at `https://callforme.tel/c/<id>`, with the transcript and result. Phone numbers and email addresses are hidden. The response is `{ "ok": true, "url": "...", "message": "..." }`. Call it again with `"public": false` to take the page down.

```json
{ "call_id": "call_8f2k1", "public": true }
```

## Prompts

The server ships MCP prompts your agent can use as starting points:

| Prompt | For |
|---|---|
| `quotes` | Call several places and compare |
| `reservation` | Book a table or appointment |
| `cancel` | Cancel a membership or service |
| `hold-for-me` | Wait on hold, patch you in |
| `negotiate-bill` | Ask for a lower bill |
| `check-stock` | See who has something in stock |

## Recommended loop

1. `find_business` if you don't have the number.
2. `plan_call` and fill any gaps it lists.
3. `place_call`. If `needs_setup` (first real call only), show `message_for_user` and wait.
4. `place_call` again with `setup_code`. On `/mcp/open`, save `account_key`.
5. `get_call` with `wait_seconds: 50` until `ended`. Answer any `pending_question`.
6. Report `answers` and `outcome` to the user. Offer `share_call` if they want to show someone.

## Limits

US and Canadian numbers only. 911, 988, 211, 311, other N11 and 900/976 numbers are blocked. Up to 3 calls to the same number per account per day. Calls end at 30 minutes. See [safety and disclosure](/docs/safety-and-disclosure).

## FAQ

### What does the Connect step do?

It's standard MCP OAuth. A browser tab opens and closes by itself, with no email, form or card, and that creates your account. The first real call then shows one setup link to add $10.

### Does the server keep session state?

No. It's stateless streamable HTTP. Every request carries its own auth token, so any client that speaks remote MCP works.

### How long should get_call wait?

Pass wait_seconds up to 50. The call returns early when the status changes or a pending_question appears.

### My client doesn't support OAuth. Can I still connect?

Yes. Use https://callforme.tel/mcp/open, which needs no sign-in, or create a key on the account page and use https://callforme.tel/mcp/k/<your key> or the header Authorization: Bearer cfm_....