<!-- VanceTel docs · /docs/mcp -->

# MCP server

The VanceTel **MCP server** exposes the phone system to AI agents over the [Model Context Protocol](/developers/glossary/mcp-server). Connect it to Claude Code, Claude Desktop, or any MCP-compatible agent and the model can send a text, look up or create a contact, and check a message's status as tool calls inside its own loop — using the same API key and the same actions you would call over REST.

  The MCP server is a thin, agent-facing wrapper over the public API. It performs the same
  write- and action-oriented operations and respects the same key scopes — it does not expose
  anything the REST API doesn't.

## What an agent can do

Once connected, an agent can drive the phone system without leaving its conversation:

- **Send a text** — dispatch an SMS/MMS from one of your numbers (mirrors `POST /messages`).
- **Look up a contact** — resolve a person by phone or name for caller ID and context.
- **Create a contact** — add someone to the shared softphone directory on the fly (mirrors `POST /contacts`).
- **Check a message's status** — fetch a message by id to see whether it delivered, so the agent can decide what to do next.

Everything the agent does also appears in the softphone app in real time, so a human stays in the loop.

## Connect the server

Add an `mcpServers` entry to your MCP client config. The example below is illustrative — pass your API key through the environment, never inline in shared config.

```json
{
  "mcpServers": {
    "netexem": {
      "command": "npx",
      "args": ["-y", "@netexem/mcp-server"],
      "env": {
        "NETEXEM_API_KEY": "sk_live_…"
      }
    }
  }
}
```

A remote (HTTP) MCP endpoint follows the same shape, with a `url` instead of a `command`:

```json
{
  "mcpServers": {
    "netexem": {
      "url": "https://api.netexem.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_…"
      }
    }
  }
}
```

  The API key carries full account access. Keep it in an environment variable or secret manager
  and never commit it to a shared repo. See [Authentication](/developers/docs/authentication).

## Tools it exposes

The server registers a small set of tools, each mapped to a real API capability. Names are illustrative:

| Tool | What it does | API equivalent |
| --- | --- | --- |
| `send_message` | Send an SMS/MMS from one of your numbers | `POST /messages` |
| `find_contact` | Resolve a contact by phone or name | `GET /contacts/{id}` |
| `create_contact` | Create a contact in the shared directory | `POST /contacts` |
| `get_message` | Read a message's status and content | `GET /messages/{id}` |

Phone numbers follow [E.164 format](/developers/glossary/e164), e.g. `+15551234567`. A `send_message` call looks like this from the agent's perspective:

```json
{
  "name": "send_message",
  "arguments": {
    "from": "+15551234567",
    "to": "+15557654321",
    "body": "Hello from the agent"
  }
}
```

## How it fits with the rest of the API

The MCP server complements — it does not replace — the [REST API](/developers/docs/api-reference) and [Webhooks](/developers/docs/webhooks):

- **REST** is for your own backend code and scheduled jobs.
- **MCP** is for AI agents acting interactively in a loop.
- **Webhooks** push inbound messages and delivery receipts to your endpoint, each [HMAC-SHA256 signed](/developers/docs/webhooks), so your system can react to activity an agent didn't initiate.

A common pattern: an agent uses MCP to send a text, the recipient replies, and a `message.received` webhook drives the follow-up — keeping humans, agents, and your backend on the same conversation.

## Next steps

- [MCP for AI workflows](/developers/mcp) — what the MCP server unlocks across your stack
- [Webhooks](/developers/docs/webhooks) — react to inbound activity in real time
- [Authentication](/developers/docs/authentication) — keys, scopes and rotation