---
title: MCP
description: Connect an agent client to bounded tools over an explicitly mapped Basalt Hosted vault.
slug: mcp
path: /mcp
section: APIs
availability: supported
nav_order: 6
canonical_url: https://developers.basaltnotes.com/mcp
markdown_url: https://developers.basaltnotes.com/mcp.md
mirror_url: https://basaltnotes.com/developers/mcp
---
# Model Context Protocol (MCP)

Basalt exposes a hosted HTTP JSON-RPC and stateless Model Context Protocol (MCP) tool endpoint conforming to protocol revision `2026-07-28` at:

```text
POST /api/mcp
```

[Machine-readable tool reference](/api/content/developers/references/mcp.json)

The supported contract is an authenticated AI-tool gateway over explicitly mapped **Basalt Hosted** content. Premium, Professional, Developer & Agent, and Team plans have independent, plan-specific MCP allowances. It is not a route into arbitrary local browser state.

## Protocol & Routing Headers

Conforming to the MCP `2026-07-28` revision, requests support standard HTTP routing headers for stateless transport:

```http
Authorization: Bearer bda_…
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
Mcp-Name: search_notes
```

- `MCP-Protocol-Version`: Specifies protocol revision (`2026-07-28`). All responses echo `MCP-Protocol-Version: 2026-07-28`.
- `Mcp-Method`: Specifies the MCP method (`server/discover`, `tools/list`, `tools/call`).
- `Mcp-Name`: Specifies the tool name when executing a tool with `tools/call`.

Standard JSON-RPC 2.0 payload bodies (`{ "jsonrpc": "2.0", "method": "...", "params": { ... }, "id": 1 }`) continue to be fully supported for bidirectional compatibility.

## Authentication

Generate a hosted access token from **Settings → AI Connections & API**. Basalt stores only its hash and supports rotation or revocation:

```http
Authorization: Bearer bda_…
Content-Type: application/json
```

Most vault tools also require a `mappingId` argument identifying the explicit Basalt Hosted mapping.

The same secure token may be used for both hosted MCP and the Developer REST API on Developer & Agent or Team plans. Each endpoint checks the account's current plan independently on every request. A Premium or Professional token therefore does not grant Developer REST API access.

MCP operations use a dedicated monthly counter and request-per-minute boundary; they do not consume Developer REST API allowance. Authentication, inactive-account, entitlement, rate-limit, and monthly-limit rejections do not consume the monthly MCP allowance. Once an authenticated request reaches a recognized protocol or tool operation, it reserves one operation before execution, including a tool call that later fails argument validation. This prevents concurrent mutation requests from executing beyond the monthly allowance.

## Server Discovery

Discover server capabilities and supported protocol revisions via `server/discover`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover"
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "server": {
      "name": "basalt-notes-hosted-mcp",
      "version": "1.0.0",
      "protocolVersion": "2026-07-28"
    },
    "protocolVersions": ["2026-07-28", "2024-11-05"],
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    }
  },
  "id": 1
}
```

## List tools

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

The V1 implementation currently exposes these tools:

| Tool | Purpose | `mappingId` |
|---|---|---|
| `search_notes` | Search paths/content in one hosted vault | Required |
| `get_note_content` | Read one hosted note and revision | Required |
| `create_or_append_note` | Preview/apply one hosted note write | Required |
| `query_graph_relations` | Query incoming/outgoing WikiLink relations | Required |
| `translate_canvas` | Convert bounded spatial nodes to a Markdown outline | Not required |
| `get_vault_schema` | Inspect bounded YAML frontmatter keys | Required |
| `apply_note_transaction` | Preview/apply a transactional note batch | Required |
| `get_knowledge_events` | Read provenance events for one mapping | Required |

## Call a tool

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "mappingId": "<uuid>",
      "query": "launch decision"
    }
  }
}
```

Successful tool results use MCP-style content records. Tool failures may return JSON-RPC errors or an MCP `isError` result depending on whether the failure is protocol-level or tool-level.

## Mutation safety

`create_or_append_note` and `apply_note_transaction` use the same hosted knowledge-transaction boundary as the REST API.

- Writes default to dry run.
- Applied writes require explicit `dryRun: false`.
- Existing-note changes should provide the current expected revision/hash.
- Applied writes require an idempotency key.
- Batch transactions are bounded.

An MCP client should preview the mutation, show the intended effect when appropriate, then explicitly apply the confirmed transaction.

## Bounded inspection

MCP operations are intentionally bounded. Current implementation limits include:

- search result limits;
- at most 500 canvas nodes for `translate_canvas`;
- a bounded frontmatter scan for `get_vault_schema` (currently up to 2,000 notes with bounded content per note);
- bounded content used for graph/frontmatter analysis;
- at most 100 actions in a note transaction.

Do not treat a truncated schema/graph response as proof that no additional information exists.

## Governance boundaries

MCP does not create a second authority model. A tool call cannot legitimately:

- read a local-only vault through the hosted gateway;
- manufacture workspace/vault authority from a guessed identifier;
- bypass current Context Scope/audience restrictions where a scoped Product Runtime workflow applies;
- confirm a Strata decision merely because an agent generated it;
- bypass Forge for consequential governed actions;
- promote unreviewed model output to trusted shared memory.

## Client configuration

Different MCP clients express HTTP endpoints and authorization differently. Use the client's supported HTTP/JSON-RPC configuration and keep the PAT in its secret/credential store. Do not paste production tokens into checked-in configuration files.

The Developer Center should provide client-specific snippets only after those client configuration formats are verified against current supported releases.