# mcp

> Use Vestra from any editor or agent that speaks MCP.

Use Vestra from any editor or AI agent that speaks MCP, the Model Context Protocol. There is one MCP endpoint, `/v1/mcp`, and any MCP client can call it with your API key. `tools/list` shows the tools it offers. To let a coding agent search these docs without a key, add the [docs MCP](https://vestra.ai/developers/docs-mcp). [Build with AI](https://vestra.ai/developers/build-with-ai.md) lists every resource for coding agents.

## TypeScript

MCP is a separate way in, so there is nothing to call from the TypeScript SDK. Point any MCP client at `https://api.vestra.ai/v1/mcp` (during the preview, `https://api-staging.vestra.ai/v1/mcp`), with your key as a Bearer token.

## Python

MCP is a separate way in, so there is nothing to call from the Python SDK. Point any MCP client at `https://api.vestra.ai/v1/mcp` (during the preview, `https://api-staging.vestra.ai/v1/mcp`), with your key as a Bearer token.

## CLI

`vestra mcp` runs a local MCP server for your editor over stdio, using the key `vestra login` saved. Add it to your editor as a stdio server, with command `vestra` and args `["mcp"]`.

## HTTP

```bash
# Connect any MCP client. Point it at this URL with your key. Over plain HTTP the endpoint speaks JSON-RPC,
# and it needs both types in the Accept header. tools/list shows the tools it offers.
curl "$VESTRA_BASE_URL/v1/mcp" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

# Connect an agent that speaks A2A. Each deployment has an agent card, and reading it needs no key.
curl "$VESTRA_BASE_URL/v1/a2a/dep_4kq/.well-known/agent-card.json"
```

## MCP

```json
{
  "mcpServers": {
    "vestra": {
      "type": "http",
      "url": "https://api-staging.vestra.ai/v1/mcp",
      "headers": { "Authorization": "Bearer vk_test_..." }
    }
  }
}
```

## Good to know

### Connecting a client

The endpoint uses MCP's streamable HTTP transport. Send your key in `Authorization: Bearer`, and send `Accept: application/json, text/event-stream`.

### The key you need

MCP needs a key with the `runtime` scope, or `all`.

### Agents that speak A2A

Each deployment also answers A2A, the Agent2Agent protocol, at `/v1/a2a/{deployment_id}`. Its agent card is at `/v1/a2a/{deployment_id}/.well-known/agent-card.json`.

## The routes behind mcp

- `POST` [/v1/mcp](https://vestra.ai/developers/reference/api/mcp-server/post-v1-mcp.md): One MCP endpoint (streamable HTTP): the card's lines as tools, each with an optional user (with none, your company's own Bash). Keys and secrets stay with people. Key scope: `runtime` (or `all`).
- `GET` [/v1/a2a/{deployment_id}/.well-known/agent-card.json](https://vestra.ai/developers/reference/api/a2a/get-v1-a2a-deployment-id-well-known-agent-card-json.md): What this deployment does and how to authenticate, for other agents to discover.
- `POST` [/v1/a2a/{deployment_id}](https://vestra.ai/developers/reference/api/a2a/post-v1-a2a-deployment-id.md): A2A JSON-RPC: send a message, stream, get, list or cancel. Push notifications are not offered; subscribe to webhooks instead. An A2A exchange is a conversation; an A2A task is its work. Key scope: `runtime` (or `all`).