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

# MCP server

> Vexa's meeting capabilities as MCP tools — 21 on the hosted service, 10 in the open-source release.

The MCP server runs as its own service and is fronted by the gateway at `/mcp` — on the **hosted
service** at `https://api.cloud.vexa.ai/mcp`, on **Kubernetes**, and on **self-hosted Docker Compose
from 0.12.18 onward**.

## Hosted and self-hosted do not carry the same tools

|                                                                        | Tools                                      | As of                                                                                                              |
| ---------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Hosted** — `https://api.cloud.vexa.ai/mcp`                           | **21** — 14 meetings and identity, 7 flows | verified by `tools/list` on 2026-09-04; `initialize` returns `Vexa MCP Service (v0.12)` over protocol `2024-11-05` |
| **Self-hosted** — Compose 0.12.18+ or Kubernetes, release **v0.12.26** | **10**                                     | the tool routes in the v0.12.26 source                                                                             |

The eleven hosted-only tools are in no open-source release or tag today. If you self-host, plan on
the ten.

## Fastest path on the hosted service

Open [vexa.ai/connect](https://vexa.ai/connect), sign in, copy the prompt into your agent; it mints a key and configures the client for you. The prompt is valid for five minutes.

## What it is

An MCP client — Claude Desktop, an IDE, any MCP-compatible agent — gets Vexa's meeting capabilities
as standard **MCP tools and prompts**, with no bespoke API integration.

The service is a stateless FastAPI app whose routes *are* the tools. Every tool call forwards the
caller's credential to the gateway as `X-API-Key`, and the gateway resolves the key and enforces
scopes. It holds no credentials and touches no database.

## Tools

### In both — hosted and self-hosted (10)

| Tool                     | What it does                                                               |
| ------------------------ | -------------------------------------------------------------------------- |
| `parse_meeting_link`     | URL to platform / `native_meeting_id` / passcode — pure, no gateway hop    |
| `request_meeting_bot`    | send a bot to a meeting (accepts `meeting_url` **or** `native_meeting_id`) |
| `get_bot_status`         | status of the bots running under your key                                  |
| `update_bot_config`      | change an active bot's configuration, e.g. the transcription language      |
| `stop_bot`               | remove an active bot from a meeting                                        |
| `list_meetings`          | your meetings, with pagination and status / platform / metadata filters    |
| `get_meeting_transcript` | segments with speaker, timestamp and text — during the meeting or after    |
| `list_recordings`        | recordings for the authenticated user                                      |
| `get_recording`          | one recording and its media files                                          |
| `report_issue`           | tell the Vexa maintainers something went wrong; a human reads every ticket |

### Hosted only (11)

Four more meeting tools:

| Tool                 | What it does                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `search_transcripts` | search what was **said** across your meetings; returns ranked snippets, not whole transcripts   |
| `annotate_meeting`   | set a meeting's title and attach your own metadata — a CRM id, a ticket, tags — during or after |
| `get_meeting_chat`   | read the in-call chat: links, spellings and side comments that were never spoken                |
| `speak_in_meeting`   | say something out loud in a live meeting through the bot; everyone present hears it             |

And seven flows tools:

| Tool              | What it does                                                                            |
| ----------------- | --------------------------------------------------------------------------------------- |
| `whats_waiting`   | what is waiting for you right now — pending reactions, with the flow that produced each |
| `timeline`        | your day in order: what happened and what is scheduled                                  |
| `flows_list`      | every flow this deployment knows, and the steps flows are built out of                  |
| `reactions_list`  | your share of the reaction queue                                                        |
| `reaction_signal` | steer one of your own reactions                                                         |
| `report_friction` | file what did not work, in your own words, for a developer to read                      |
| `friction_so_far` | your own filed reports, newest first                                                    |

`speak_in_meeting` is irreversible and visible to real people in a real conversation. Call it only
when the person you work for has asked you to say that thing.

### Prompts

Four, on both: `vexa.meeting_prep` · `vexa.during_meeting` · `vexa.post_meeting` ·
`vexa.teams_link_help`.

## Connect a client

Point the client at the **gateway**, not at the MCP service's own port — the gateway is the
authenticated front door.

**Don't have a key yet?** Hosted: sign in at [vexa.ai/signin](https://vexa.ai/signin) with a Google
account and copy your key from [your account page](https://vexa.ai/account) — free credit, no card
required. Self-hosted: `make all` prints a key when the stack comes up.

**Claude Code, as a plugin** — the repository is a plugin marketplace; the plugin carries the server config and two skills (meetings, setup), and asks for your key on install:

```text Claude Code plugin theme={null}
/plugin marketplace add Vexa-ai/vexa
/plugin install vexa@vexa
```

Every client below takes the remote URL and a bearer header natively — no bridge process. Use the
hosted URL, or your own gateway's `/mcp` (Docker Compose: `http://localhost:18056/mcp`).

```bash Claude Code theme={null}
claude mcp add --transport http vexa https://api.cloud.vexa.ai/mcp --header "Authorization: Bearer $VEXA_API_KEY" -s user
```

```bash Codex CLI theme={null}
export VEXA_API_KEY=<your key>
codex mcp add vexa --url https://api.cloud.vexa.ai/mcp --bearer-token-env-var VEXA_API_KEY
# or, in ~/.codex/config.toml:
#   [mcp_servers.vexa]
#   url = "https://api.cloud.vexa.ai/mcp"
#   http_headers = { Authorization = "Bearer <your key>" }
```

```json Cursor (.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "vexa": {
      "url": "https://api.cloud.vexa.ai/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}
```

```bash Gemini CLI theme={null}
gemini mcp add -t http -H "Authorization: Bearer $VEXA_API_KEY" vexa https://api.cloud.vexa.ai/mcp
```

```json Windsurf (mcp_config.json — the key is serverUrl) theme={null}
{
  "mcpServers": {
    "vexa": {
      "serverUrl": "https://api.cloud.vexa.ai/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}
```

Merge into a config file that already has other servers; do not overwrite it. Or skip all of this:
[vexa.ai/connect](https://vexa.ai/connect) hands your agent a prompt that registers the server itself.

**Clients that cannot send a header** (Claude Desktop and other GUI clients) go through the
`mcp-remote` bridge instead:

```json Claude Desktop (mcp-remote bridge) theme={null}
{
  "mcpServers": {
    "Vexa": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.cloud.vexa.ai/mcp",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your key>" }
    }
  }
}
```

(The header value goes through `env` because `mcp-remote` mangles spaces inside `args` on some
clients — its README's own workaround.)

Self-hosted compose requires **0.12.18 or later** — that is the release in which the gateway began
fronting `/mcp`. `18056` is the compose `API_GATEWAY_HOST_PORT`.

The key may arrive as `X-API-Key` or as the MCP transport's `Authorization: Bearer <key>`; both are
forwarded on. Auth at the edge is fail-closed and identical to every other route
([Authentication](/authentication)).

<Note>
  The MCP service also publishes a direct host port (`127.0.0.1:18010` by default) for local
  debugging. **It bypasses the gateway, and therefore bypasses authentication.** Do not expose it.
</Note>

### How the transport is forwarded

The two legs of streamable HTTP are forwarded differently, and the difference is the point
([#795](https://github.com/Vexa-ai/vexa/issues/795)):

| Leg                                                | What it is                                                                     | How the gateway forwards it                             |
| -------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------- |
| `POST /mcp` (and `PUT`/`PATCH`/`DELETE`/`OPTIONS`) | a message — short request/response JSON                                        | buffered forward, status and body verbatim              |
| `GET /mcp`                                         | the server-to-client SSE stream: headers, then silence until the server pushes | **relayed unbuffered**, on a dedicated streaming client |

Buffering the `GET` leg is what produced the original failure: the proxy waits on the next body read
of a healthy-but-silent stream, hits its read timeout, and manufactures a `503` the MCP service
never sees.

## What is not available

* **Tools blocked on API parity**, on hosted and self-hosted alike — these wrap REST routes the
  public API does not expose yet, and will be ported when the routes land: `delete_recording` ·
  `get_recording_media_download` · `get_recording_config` / `update_recording_config` ·
  `create_transcript_share_link` · `delete_meeting` · `get_meeting_bundle`.

The live status row for this feature is maintained on [Roadmap → Status](/roadmap/status).