Claude Code and other MCP clients
Connect Claude Code, Cursor, and other MCP clients to Trillet with an API key, over the hosted server or the local npm package.
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 | 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 | 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.
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.
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.
Claude Code
Add the hosted server with your API key and workspace id:
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:
claude mcp list
Then ask Claude Code to "list my Trillet agents" to confirm your key works.
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.
Cursor and other local clients
The server is published on npm as @trillet-ai/mcp. It reads your credentials from environment variables.
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"trillet": {
"command": "npx",
"args": ["-y", "@trillet-ai/mcp@latest"],
"env": {
"TRILLET_API_KEY": "YOUR_API_KEY",
"TRILLET_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
}
}
}
}Claude Desktop extension
Most Claude Desktop users should use the Claude connector 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.mcpbfrom 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.
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:
AuthorizationstringrequiredBearer <your Trillet API key>
X-Trillet-Workspace-IdstringrequiredThe 24-character id of the workspace to work in.
The REST API uses an x-api-key header. The MCP server uses Authorization: Bearer because that is the header MCP clients send.
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:
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.
Last updated on