---
title: MCP integration
description: Connect AI agents to Agent Number via Model Context Protocol (MCP).
url: https://agentnumber.really.com/docs/mcp
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

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

# MCP integration

> Connect AI agent runtimes (Anthropic, OpenAI, custom) to Agent Number via Model Context Protocol. One endpoint, thirteen tools, zero adapters.

## Endpoint

MCP server (streamable-http transport):

```text
https://agentnumber.really.com/mcp
```

Discoverable from our [MCP server card](/.well-known/mcp/server-card.json) at `/.well-known/mcp/server-card.json`.

## Install in Claude Code

One line registers Agent Number as an MCP server in your Claude Code session:

```bash
claude mcp add agent-number https://agentnumber.really.com/mcp
```

Other MCP-aware runtimes — Cursor, Zed, ChatGPT, OpenClaw — point their MCP client at the same URL (streamable-http transport).

## Initialize

Standard MCP handshake. The server returns its protocol version + capabilities:

```bash
curl -X POST https://agentnumber.really.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }'
```

## Tools

Call `tools/list` to discover, then invoke directly. The full tool catalog with arguments and response shapes lives on the dedicated [Tools](/docs/mcp/tools) page.

## Authentication via MCP

Bearer-token tools require `Authorization: Bearer <token>` on the MCP request itself. Mint a token via `subscribe` (after payment) or `auth` (wallet-signature recovery). See [Auth](/docs/auth).

## Try the demo first

Before paying, call `try_demo`. It's a free, no-auth simulated walkthrough — the response shapes match the real endpoints exactly, so you can scaffold your integration and verify wiring before the real subscribe:

```bash
curl -X POST https://agentnumber.really.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "demo",
    "method": "tools/call",
    "params": {"name": "try_demo", "arguments": {}}
  }'
```

## Long-poll behavior (`receive_sms`)

`receive_sms` holds the request open up to `wait_seconds` (default 30, max 120) and emits MCP `notifications/progress` every 20 seconds to keep the client alive indefinitely. Near-instant OTP delivery end-to-end.

## Discovery files for crawlers and agents

- [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json) — full MCP server card
- [`/.well-known/mcp.json`](/.well-known/mcp.json) — compact MCP descriptor
- [`/.well-known/agent-card.json`](/.well-known/agent-card.json) — A2A Agent Card
- [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json) — Anthropic Agent Skills index
- [`/agent-skill/SKILL.md`](/agent-skill/SKILL.md) — full SKILL.md (digest-verified)

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

← Previous: [Quickstart](/docs/quickstart) · Next: [Auth](/docs/auth) →