MCP server
Connect an AI assistant to Spiral through the Model Context Protocol.
Connect an AI assistant such as Claude or ChatGPT to Spiral so it can answer questions about your Projects: which Projects you have, which branches exist, and which Tables and other resources each branch holds. The assistant signs in as you, asks for your consent, and gets read-only access. It cannot read the rows inside a Table yet.
The assistant talks to the Spiral MCP server through the Model Context Protocol, which Claude, ChatGPT, and VS Code support.
Connect a client
Add a remote MCP server to your client with the URL for your region:
| Region | MCP server URL |
|---|---|
| Default | https://api.spiraldb.dev/mcp |
| EU | https://eu.api.spiraldb.dev/mcp |
- Add the server URL in your MCP client.
- Sign in to Spiral in the browser window that the client opens.
- Read the consent screen. It names the client and the access it asks for.
- Approve the request.
The client now has a token that works only for the MCP server. If the token leaks, it cannot be used against the rest of the Spiral API.
What the assistant can see
Every tool is read-only and returns Project metadata, not Table rows.
| Tool | Returns | Scope |
|---|---|---|
list_projects | The Projects that you can see, with their IDs and descriptions. | projects:read |
list_branches | The branches of a Project, each with its head commit. | catalog:read |
list_resources | The resources and namespaces (path prefixes) of a Project at a commit. | catalog:read |
list_branches and list_resources return results in pages. The client
passes the nextPageToken of one page as pageToken to get the next one.
Access and scopes
A scope limits what the assistant can do on your behalf; it never adds
permissions. A tool call needs both the scope in the token and the permission
in the Project, so the assistant can never see more than you can. If the token
lacks a tool's scope, the server returns 403 with a challenge that names the
scopes to request. For the permission model, see
Authorization.
Disconnect a client
Open Connected applications in the account menu of Studio and revoke the client. The client can no longer refresh its token in any Organization, and any access token it already holds expires within one hour.
For client developers
The server accepts clients that identify themselves with a Client ID Metadata
Document, that is, a client_id that is an HTTPS URL. Documents from these
hosts are accepted:
claude.aichatgpt.comvscode.dev
A client without a metadata document must be registered by Spiral. To request a registration, contact hello@spiraldb.com.