---
title: "Trickest MCP server"
canonical: https://trickest.com/docs/developer-tools/mcp
description: "Connect Claude, Claude Code, Cursor, Codex, or any MCP client to the hosted Trickest MCP server, sign in once, and let the agent build and run workflows with its own tools."
---
# Trickest MCP server
The Trickest MCP server is a hosted [Model Context Protocol](https://modelcontextprotocol.io) endpoint:
```text
https://api.trickest.io/mcp
```
Any MCP client that speaks Streamable HTTP can connect to it. Once connected, the agent gets 40 typed tools that cover the platform: search the library, read and edit workflow graphs, start runs and wait for them, read outputs, query Live Tables, and manage variables and workspace memory. There is nothing to install and nothing to self-host.
This page is about external agents driving Trickest. The in-app Trickest agent can also
**consume** MCP servers of its own, registered under **Settings > Agent > MCP Servers** on
workspaces that have that option. Those are two separate systems.
## Two ways to authenticate
| Method | Best for | What the agent holds |
|---|---|---|
| **Sign in (OAuth)** | Claude on the web and desktop, Claude Code, Codex, and any client that runs an OAuth flow | A connection you approve once in the browser. Tokens rotate on their own and you can revoke the connection from Settings. |
| **API token** | Cursor, CI jobs, custom clients, and any client that only takes a headers block | Your personal API token from **Settings > Credentials**, sent as `Authorization: Token `. |
Both methods act as **you**: the same permissions, the same workspace, the same audit trail. Neither one narrows the scope for the agent.
Sign-in uses OAuth 2.1 with PKCE. The server publishes its metadata at `https://api.trickest.io/.well-known/oauth-protected-resource/mcp` and `https://trickest.io/.well-known/oauth-authorization-server`, so a compatible client discovers the flow from the endpoint alone. Clients identify themselves with a [Client ID Metadata Document](https://modelcontextprotocol.io/specification/draft/basic/authorization); there is no client registration step and no client secret.
## Connect a client
Works in Claude on the web and in the desktop app.
Open **Settings > Connectors**, choose **Add custom connector**, name it `Trickest`, and paste `https://api.trickest.io/mcp` as the URL.
Click **Connect**. A Trickest window opens. Sign in if you are not already, review the request, and click **Authorize**.
In the composer, open the **+** menu, then **Connectors**, and switch **Trickest** on. The agent now lists the Trickest tools.
Back in **Settings > Connectors > Trickest**, Claude groups the tools by effect. Leave the 23 read-only tools on **Always allow** so lookups run without a prompt, and keep the tools that write, run, or delete on **Ask** so nothing changes in your workspace without you.
Add the server, then sign in from inside the session:
```bash
claude mcp add --transport http trickest https://api.trickest.io/mcp
```
Start `claude`, run `/mcp`, pick **trickest**, and follow the browser sign-in. Claude Code stores the connection and refreshes it on its own.
For a headless machine or CI, skip the sign-in and pass a token instead:
```bash
claude mcp add --transport http trickest https://api.trickest.io/mcp \
--header "Authorization: Token $TRICKEST_TOKEN"
```
Add the server to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) with your API token in the headers block:
```json
{
"mcpServers": {
"trickest": {
"url": "https://api.trickest.io/mcp",
"headers": {
"Authorization": "Token "
}
}
}
}
```
Cursor reads `${env:TRICKEST_TOKEN}` inside the header value if you prefer to keep the token out of the file.
Add the server and sign in:
```bash
codex mcp add trickest --url https://api.trickest.io/mcp
codex mcp login trickest
```
Or pin a token in `~/.codex/config.toml` for headless use:
```toml
[mcp_servers.trickest]
url = "https://api.trickest.io/mcp"
http_headers = { Authorization = "Token " }
```
Any Streamable HTTP client works. If the client can run an OAuth flow, point it at the URL and let it discover the rest. If it only takes headers, send the API token:
```json
{
"mcpServers": {
"trickest": {
"url": "https://api.trickest.io/mcp",
"headers": {
"Authorization": "Token "
}
}
}
}
```
`Bearer` is also accepted, for session JWTs and for existing configurations.
## The sign-in flow
The client opens `https://trickest.io/oauth/authorize` in your browser. The page names the application asking, what it calls itself, your account, and the address you return to after approving.
The page states what the connection can do: everything your account can, including running workflows and changing workspace data. **Authorize** creates the connection. **Decline** sends the client back with an error and stores nothing.
Trickest issues the client an access token and a refresh token that belong to that connection alone, not to your browser session. The access token is valid for two hours and refreshes in the background. The connection stays alive as long as the client keeps using it; one that goes unused for 14 days expires on its own.
Open [Settings > Credentials](https://trickest.io/settings/credentials). Under **Connected apps** each connection shows the application host, its connection date, and its last use.
Only approve a request you started yourself. A request that returns to `localhost` comes from a program on your own computer, such as Claude Code or Codex; approve it only if you just ran that program.
## Tool permissions
Every tool carries MCP annotations that say whether it reads, writes, or deletes. Clients use them to decide when to ask you.
| Class | Count | Examples | What clients do |
|---|---|---|---|
| Read-only | 23 | `trickest_workflow_get`, `trickest_run_get`, `trickest_database_query`, `trickest_query` | Claude offers **Always allow** for the whole group, so lookups run without a prompt. |
| Write | 10 | `trickest_node_add`, `trickest_connect`, `trickest_workflow_create`, `trickest_write` | Prompt per call by default. |
| Destructive | 7 | `trickest_run_execute`, `trickest_workflow_delete`, `trickest_node_remove`, `trickest_variable_set`, `trickest_variable_rm`, `trickest_delete`, `trickest_execute` | Prompt per call. `trickest_workflow_delete`, `trickest_variable_rm`, `trickest_delete`, and `trickest_execute` also refuse to act until the agent passes `confirm: true`; without it they return a summary of what would happen. |
`trickest_run_execute` counts as destructive because it spends fleet compute. Keep it on **Ask** unless you are running an unattended job. The full list is on the [tool reference](/docs/developer-tools/mcp/tools).
## Disconnect and revoke
- **A signed-in connection:** open [Settings > Credentials](https://trickest.io/settings/credentials), find it under **Connected apps**, and click **Disconnect**. The client's next call fails with a 401 and it has to ask you again. Disconnecting from the client side (for example **Disconnect** in Claude's connector settings) removes it there but does not revoke it in Trickest; do both when you want it gone.
- **An API token:** regenerate it on the same page. Every client that holds the old token stops working at once, including the CLI and SDK.
The Trickest CLI's `trickest auth login` creates a connection the same way, labelled **Trickest CLI**. Revoking it signs that machine out.
## Limits
- **A signed-in connection cannot reach sandboxes.** The server hides the `app.*` command group (sandbox exec, files, previews) from search and refuses it on dispatch, because a sandbox can expose the credentials inside it. Use an API token when the agent needs a sandbox, or the [Sandbox SDK](/docs/developer-tools/sandbox-sdk).
- **No local files.** The server runs in Trickest's infrastructure, so tools take script code inline (`code` or `codeB64`), and storage push and pull are not offered over HTTP.
- **Bounded waits.** `trickest_run_execute` and `trickest_run_wait` return after 45 seconds by default with `terminal: false` when a run is still going. Call `trickest_run_wait` again rather than polling `trickest_run_get` in a loop.
- **Output size.** `trickest_output_read` returns at most 50 KB of one file and sets `truncated: true` past that. The server accepts request bodies up to 4 MB.
- **One user, full permissions.** Both methods act with your role. There is no per-agent scope; give an agent a separate Trickest user if it needs less.
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `401` with `WWW-Authenticate: Bearer … resource_metadata=…` | No credential, an expired token that could not refresh, or a disconnected connection. | Reconnect from the client. For a token, check the header reads `Token ` and the token still exists in Settings. |
| `Invalid authorization request` on the consent page | The client identified itself with a metadata document Trickest could not fetch or trust, or asked to return somewhere that document does not list. | Update the client. Trickest only follows `https` return addresses on the client's own origin, or `http://localhost`. |
| A tool returns `needsConfirmation` instead of acting | The tool is destructive and the agent did not pass `confirm: true`. | Read the summary, then let the agent call again with `confirm: true`. |
| `memoization not possible` from `trickest_run_execute` | You asked for a single-node run but the graph changed since the last run. | Run the whole workflow (omit `node`). |
| Sandbox commands are missing | The client connected through sign-in. | Use an API token for that client, or the Sandbox SDK. |
## Next steps
Every tool, what it does, and whether it reads, writes, or deletes.
Pick between MCP, the CLI, the SDK, and skills.
The API token, and how the CLI signs in.
The permissions an agent inherits from your role.
---
_Markdown source of https://trickest.com/docs/developer-tools/mcp._