API and MCP

Connect an AI assistant

Spice Labs runs an MCP server that AI assistants and coding agents can connect to. Once connected, an assistant can read the Spice Labs API and CLI references and call the API for you, with your permissions and only what you allow. There is no token to copy: you sign in and approve the assistant once.

Connect

Add the server to your assistant

The address is https://api.spicelabs.io/mcp. In Claude Code:
```
claude mcp add --transport http spice-labs https://api.spicelabs.io/mcp
```
In pi, include --url; without it, pi saves the address as a command to run:
```
pi mcp add spice-labs --url https://api.spicelabs.io/mcp
```
Other assistants call this a remote MCP server, a connector or a custom integration; give them the same address. The dashboard’s Survey setup page (menu ☰) shows it too, in step 5. An assistant set up through a JSON file needs only the address:
```
{ "mcpServers": { "spice-labs": { "url": "https://api.spicelabs.io/mcp" } } }
```
Do not add an Authorization header. The MCP server does not accept API tokens or Spice Passes, and a header can stop the assistant from offering the sign-in.
Sign in and approve

The first time the assistant connects, it opens your browser. Some assistants wait for you to start the sign-in yourself; in pi, run pi mcp login spice-labs. Sign in to Spice Labs and you land on a page titled Connect app to Spice Labs. It names the app and says where you return afterwards. Choose the organization the app will work in, the projects it can use, and what to allow, then select Allow.
Ask it something

For example: “List my Spice Labs projects and their latest surveys”, “Which API operations read a report’s sections?” or “Show the CLI command to survey ./build/libs and upload it”.

Projects it can use

On the consent page, choose All projects, including ones created later, or Only the projects I choose and tick the projects. The assistant sees and works with only those projects. When it needs a project you did not choose, it asks, and the consent page opens again with your earlier choices ticked and that project added.

What you can allow

Choice on the consent page	What it lets the assistant do	Ticked at first
Read the Spice Labs API and CLI documentation	Read the references and list your projects	Yes
Read data in your projects	Call read-only API operations	Yes
Change and delete data in your projects	Call operations that create, change or delete	No
Create API tokens and Spice Passes, with at most your own permissions	Create a 1-hour API token or a 48-hour Spice Pass for a script or a survey	No

The assistant always acts as you, with your current permissions on each project, so it can never do more than you can. A Spice Pass, or an API token that changes data, also needs Change and delete data in your projects. When the assistant needs something you have not allowed, it asks, and the consent page opens again with your earlier choices already ticked.

What the assistant can do

The server gives the assistant a small set of tools:

Tool	Purpose
`list_projects`	The projects you can see in the organization, with their ids
`api_search`, `api_operation`, `api_object`	Find API operations and read an operation or a schema exactly as the reference states it
`cli_reference`	The reference for the latest Surveyor CLI release
`api_get`	Call a read-only operation as you
`api_change`, `api_delete`	Call an operation that creates, changes or deletes, as you
`create_api_token`, `create_spice_pass`	Create a short-lived credential

The assistant works from the same API reference as a script would, so every operation in the API is available to it, within what you allowed. It cannot upload surveys; surveys come from the Surveyor CLI.

Disconnect

Every assistant you connect is listed under Connected apps on the Credentials page, with what it may do, the projects it can use, when it connected and when it was last used. Disconnect stops it immediately and cancels the API tokens and Spice Passes it created. If you are removed from an organization, your connected apps stop working there too.

Access stays connected while you use it. An assistant you do not use for 90 days has to be approved again.