---
title: "Claude Code and other MCP clients"
sidebarTitle: "Claude Code and other clients"
description: "Connect Claude Code, Cursor, and other MCP clients to Trillet with an API key, over the hosted server or the local npm package."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

ChatGPT and Claude.ai sign in to Trillet with your login. Developer tools such as Claude Code and Cursor usually connect with an **API key** instead. This page covers those setups.

| | Hosted server | Local package |
|---|---|---|
| **How** | Your client connects to `https://mcp.trillet.ai/mcp` | Your client runs `npx -y @trillet-ai/mcp@latest` on your computer |
| **Needs** | A client that supports remote MCP servers and custom headers | Node.js 18 or later |
| **Good for** | Claude Code, and any client that speaks Streamable HTTP | Cursor, Windsurf, and any client that runs local (stdio) servers |
| **Version** | 0.10.0, always the current release | The latest version on npm, currently 0.8.1 |

Both routes act on the same Trillet account, but they don't offer the same features yet. The npm package is behind the hosted server:

| | Hosted server (0.10.0) | npm package (0.8.1) |
|---|---|---|
| Tools | All 85 in the [tool reference](https://trillet-ai.jamdesk.app/mcp/tools/index) | 83: no `trillet_list_workspaces` or `trillet_switch_workspace` |
| `workspace_id` | Workspace id or name | Workspace id only |
| Text test calls | `trillet_say` and `trillet_end_text_call` take `text_call_id` | They take `session_id` instead |
| [Prompts, resources, confirmation forms, progress, structured results](https://trillet-ai.jamdesk.app/mcp/prompts-and-resources) | Yes | No |
| Uploading a file from your computer to a knowledge base (`file_path`) | No | Yes |

Use the hosted server if you want everything in these docs. The tool reference describes the hosted server.

## Before you start

You need two values from the [Trillet dashboard](https://app.trillet.ai).

<Columns cols={2}>
  <Card title="API key" icon="key" href="https://app.trillet.ai/settings?section=api-keys">
    **Settings > Developer > API Keys.** Create a key and copy it. It is shown only once.
  </Card>
  <Card title="Workspace ID" icon="briefcase" href="https://app.trillet.ai/settings?section=workspace-details">
    **Settings > Workspace > Workspace Details.** A 24-character id with a copy button. You can also use **Copy workspace ID** in the workspace switcher.
  </Card>
</Columns>

<Note>
  Don't see **API Keys** under **Developer**? API keys are not available on SMB plans, and on other plans you need the `api_keys:view` permission. Ask a workspace owner to create a key for you or to grant the permission.
</Note>

<Warning>
  An API key acts as you, with your role, in every workspace you belong to, not just the one you set here. Keep it out of shared chats, screenshots, and source control. You can revoke a key and create a new one at any time on the same settings page.
</Warning>

## Claude Code

Add the hosted server with your API key and workspace id:

```bash
claude mcp add --transport http trillet https://mcp.trillet.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Trillet-Workspace-Id: YOUR_WORKSPACE_ID"
```

Check that it is connected:

```bash
claude mcp list
```

Then ask Claude Code to "list my Trillet agents" to confirm your key works.

<Tip>
  To run the server locally instead, use `claude mcp add trillet -e TRILLET_API_KEY=YOUR_API_KEY -e TRILLET_WORKSPACE_ID=YOUR_WORKSPACE_ID -- npx -y @trillet-ai/mcp@latest`.
</Tip>

## Cursor and other local clients

The server is published on npm as [`@trillet-ai/mcp`](https://www.npmjs.com/package/@trillet-ai/mcp). It reads your credentials from environment variables.

### Cursor

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "trillet": {
      "command": "npx",
      "args": ["-y", "@trillet-ai/mcp@latest"],
      "env": {
        "TRILLET_API_KEY": "YOUR_API_KEY",
        "TRILLET_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
      }
    }
  }
}
```

### Other clients

Any MCP client that runs local servers can start Trillet with:

```bash
TRILLET_API_KEY=YOUR_API_KEY \
TRILLET_WORKSPACE_ID=YOUR_WORKSPACE_ID \
npx -y @trillet-ai/mcp@latest
```

Optional: set `TRILLET_API_URL` to change the API base URL. The default is `https://api.trillet.ai`.

## Claude Desktop extension

Most Claude Desktop users should use the [Claude connector](https://trillet-ai.jamdesk.app/mcp/claude) instead. It signs in with your Trillet login and stays up to date on its own.

If you use the Trillet Desktop extension (`trillet.mcpb`):

- It stores your API key in your operating system's keychain.
- **Claude Desktop never updates extensions automatically.** To get a new version, get the latest `trillet.mcpb` from Trillet support and install it again.
- To see which version you have, open **Settings > Extensions** in Claude Desktop and select Trillet.
- Versions before 0.8.3 can't finish text test calls. See [Troubleshooting](https://trillet-ai.jamdesk.app/mcp/troubleshooting#text-test-calls).

To install or update, open `trillet.mcpb` (double-click it or drag it into Claude Desktop), then enter your API key and workspace id when asked.

## Hosted server reference

Use this section to connect a client that is not listed above.

```
POST https://mcp.trillet.ai/mcp
```

The server uses Streamable HTTP. ChatGPT, Claude.ai, and Claude Desktop sign in with a Trillet login over OAuth. Another client can use OAuth only if it receives the sign-in on a loopback address (`localhost`, `127.0.0.1`, or `[::1]`). Trillet refuses other redirect addresses, including custom schemes such as `cursor://`, so use an API key with Cursor and with any client whose sign-in doesn't come back to a loopback address. Clients that send headers can use an API key:

<ParamField header="Authorization" type="string" required>
  `Bearer <your Trillet API key>`
</ParamField>

<ParamField header="X-Trillet-Workspace-Id" type="string" required>
  The 24-character id of the workspace to work in.
</ParamField>

<Note>
  The REST API uses an `x-api-key` header. The MCP server uses `Authorization: Bearer` because that is the header MCP clients send.
</Note>

If your client can set only one header, pass the workspace id in the URL instead:

```
https://mcp.trillet.ai/mcp?workspace=YOUR_WORKSPACE_ID
```

The workspace id is not a secret, so it is safe in a URL. The API key is accepted only in the `Authorization` header, never in the URL, so it stays out of browser history and server logs.

To check connectivity from a terminal:

```bash
curl -X POST https://mcp.trillet.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Trillet-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'
```

A successful response includes an `Mcp-Session-Id` header. Send it with every later request in the session.

## Work in other workspaces

Every tool accepts an optional `workspace_id`, so one connection can work across several workspaces as long as your API key's user is a member of each. Ask "list the agents in workspace `a3a3a3a3a3a3a3a3a3a3a3a3`" and the assistant passes the id through. On the hosted server you can also use the workspace name.
