# MCP Server

> Model Context Protocol (MCP) server for AI agents.

`POST https://api.bavest.co/v2/mcp`

Group: AI. Route id: `v2_mcp`. Free in every plan, including the trial.

## Description

Model Context Protocol (MCP) server for AI agents. Connect any MCP client (Claude, ChatGPT, Cursor, VS Code, Windsurf or your own agent) to one URL, `https://api.bavest.co/v2/mcp`, and use the Bavest v2 data routes as tools.

### Quick start

```json
{
  "mcpServers": {
    "bavest": {
      "url": "https://api.bavest.co/v2/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

### Tools

Each tool wraps one REST route and is named after the route's `operationId` in snake case: `equities.profile` is `equities_profile`, `etfs.topHoldings` is `etfs_top_holdings`. `initialize` and `tools/list` work without a key and return the exact names and input schemas. A tool call counts against your plan like the REST call it wraps; a route outside your plan answers with an error.

### Authentication

Send your API key in the `x-api-key` header, as on every REST route. Connectors that can only take a URL (Claude custom connectors, ChatGPT developer mode) may pass the same key as the optional `api_key` query parameter instead. URLs end up in logs and settings exports, so prefer the header.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

None besides the API key: send it in the `x-api-key` header (preferred). Connectors that cannot set headers may send it as the optional `api_key` query parameter instead; URLs end up in logs, so use that only where no header is possible.

## Request body

JSON, required. JSON-RPC 2.0 request following the MCP specification.

| Field | Type | Always present | Description |
|---|---|---|---|
| `jsonrpc` | string | yes | JSON-RPC protocol version. One of `2.0`. |
| `id` | string | no | Request identifier (omit for notifications) |
| `method` | string | yes | MCP method to invoke. One of `initialize`, `tools/list`, `tools/call`, `ping`. |
| `params` | object | no | Method parameters (varies by method) |

## Response

200 MCP server response. The response format follows the Model Context Protocol specification and varies based on the MCP method invoked by the client. (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `jsonrpc` | string | no | JSON-RPC version. Example: `2.0`. |
| `id` | string | no | Request identifier. |
| `result` | object | no | MCP response payload (varies by method) |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl -X POST 'https://api.bavest.co/v2/mcp' \
  -H "x-api-key: $BAVEST_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'
```

## Example response

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "equities_profile",
        "description": "Get company profile by symbol or ISIN",
        "inputSchema": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "Ticker symbol (e.g. AAPL)"
            }
          },
          "required": [
            "symbol"
          ]
        }
      }
    ]
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_mcp
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt