---
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 [typed tools](/docs/developer-tools/mcp/tools) for platform tasks: search the library, read and edit workflow graphs, start runs and wait for them, read outputs, query Live Tables, and manage variables and vault 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 > Personal > API & apps**, sent as `Authorization: Token `. |
Both methods use your account’s role and accessible resources. OAuth connections additionally block sandbox commands; see [Limits](#limits). Client approval settings control when the agent can use the available tools.
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
Follow [Claude’s custom connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). Team and Enterprise accounts may need an administrator to add the connector first.
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.
Review the connector’s tool permissions. Require approval for actions that change data or start runs. Available settings depend on your client and organization policy.
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 supports environment interpolation](https://prod.cursor.com/docs/mcp#config-interpolation): use `Token ${env:TRICKEST_TOKEN}` in the header and make that environment variable available to Cursor. Keep credentials out of committed project files.
Add the server and sign in:
```bash
codex mcp add trickest --url https://api.trickest.io/mcp
codex mcp login trickest
```
For token authentication, expose `TRICKEST_TOKEN` in the environment and configure its name:
```bash
codex mcp add trickest --url https://api.trickest.io/mcp \
--bearer-token-env-var TRICKEST_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: access to platform resources under your account, including running workflows and changing 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. Compatible clients refresh access tokens in the background. The default access lifetime is two hours and the fallback refresh lifetime is 14 days; issued credentials can specify a different expiry. Reconnect if refresh fails.
Open [Settings > Personal > API & apps](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 can use these hints when applying their permission policy. An annotation does not guarantee a confirmation prompt.
| Class | Count | Examples | Recommended handling |
|---|---|---|---|
| Read-only | 23 | `trickest_workflow_get`, `trickest_run_get`, `trickest_database_query`, `trickest_query` | Allow automatic reads only when appropriate for the data available to this account. |
| Write | 10 | `trickest_node_add`, `trickest_connect`, `trickest_workflow_create`, `trickest_write` | Review changes before allowing the call. |
| Destructive | 7 | `trickest_run_execute`, `trickest_workflow_delete`, `trickest_node_remove`, `trickest_variable_set`, `trickest_variable_rm`, `trickest_delete`, `trickest_execute` | Review the action. `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 > Personal > API & apps](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 an allowed loopback address such as `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._