---
title: "SDK agent integrations"
canonical: https://trickest.com/docs/developer-tools/sdk/agent-integrations
description: "Connect Trickest to Claude Code, Cursor, Codex, custom agents, and sandbox apps through the SDK, CLI, MCP, and skills."
---

# SDK agent integrations

Connect your code or coding agent through the SDKs, CLI, MCP, or skills. Use the
**platform SDK** when you are writing TypeScript, the **CLI** when a human or agent is in a
terminal, **Model Context Protocol (MCP)** when an external coding agent needs tools, and **skills** when
you want the agent to follow a repeatable playbook.

<Note>
  Install the SDK from npm or the CLI as a standalone binary. For MCP, connect
  to the hosted service at `https://api.trickest.io/mcp` and sign in, or pass an
  API token. Setup for each client is on the [MCP page](/docs/developer-tools/mcp).
</Note>

## Which path to use

<CardGroup cols={2}>
  <Card
    title="Platform operations from TypeScript"
    icon="code-branch"
    href="/docs/developer-tools/sdk/client-setup"
  >
    Use `@trickest/sdk`. Set `TRICKEST_TOKEN`, construct `TrickestClient`, then
    call typed namespaces such as `client.workflows`, `client.runs`,
    `client.database`, and `client.sessions`.
  </Card>
  <Card
    title="An execution environment for your agent"
    icon="terminal"
    href="/docs/developer-tools/sandbox-sdk"
  >
    Use the separate `@trickest/sandbox` package to create a Linux environment,
    write files, run commands, expose previews, and delete it after collecting
    results. It requires Node 22+ and an explicitly supplied token.
  </Card>
  <Card
    title="Terminal, sandbox, or CI"
    icon="terminal"
    href="/docs/developer-tools/cli"
  >
    Use the `trickest` CLI. It is built for machine-readable output, active
    context, workflow editing, run monitoring, database queries, memory,
    sessions, and skills.
  </Card>
  <Card
    title="Claude, Claude Code, Cursor, or Codex"
    icon="robot"
    href="/docs/developer-tools/mcp"
  >
    Point your MCP client at the hosted endpoint `https://api.trickest.io/mcp`.
    Sign in once from the client, or pass an API token. The agent then discovers
    and calls 40 workflow, run, output, and data tools.
  </Card>
  <Card
    title="Repeatable agent playbooks"
    icon="book"
    href="/docs/developer-tools/sdk/memory-skills"
  >
    Use Trickest skills. A skill is a markdown instruction file that teaches the
    agent how to use the CLI, SDK, workflow edits, Live Tables, or sandbox
    files.
  </Card>
</CardGroup>

## SDK: typed calls from your code

Use `@trickest/sdk` in server-side TypeScript to read platform resources or run workflows and agent turns. This example reads an existing Live Table. Supply the string `workflowId` for the workflow that owns the table.

```ts
import { TrickestClient } from "@trickest/sdk";

const client = new TrickestClient({
  token: process.env.TRICKEST_TOKEN,
  baseUrl: process.env.TRICKEST_BASE_URL ?? "https://trickest.io",
});
const table = await client.database.resolveByName("findings", workflowId);
if (!table) throw new Error("The workflow has no findings table");
const findings = await client.database.query(table.id, 'severity = "high"', {
  limit: 100,
});
console.log(findings);
```

- `TRICKEST_BASE_URL` is the web app origin, for example `https://trickest.io`.
- `database.query()` takes TQL filter expressions. For agent conversations, use a `SessionHandle`; close it when its consumer finishes. The [session guide](/docs/developer-tools/sdk/sessions) covers subscriptions, `runTurn()`, interrupts, and cancellation.
- Keep `TRICKEST_TOKEN` in your server environment. Browser components should call your server route instead of importing an authenticated client.

### Use both SDKs together

`@trickest/sdk` and `@trickest/sandbox` can be installed in the same application. For example, read table metadata with the platform client, then process collected data in a standalone sandbox. Install each package explicitly; neither includes the other.

The platform SDK controls workflows, tables, and agent conversations. The [Sandbox SDK](/docs/developer-tools/sandbox-sdk) creates direct execution environments with `Sandbox.create()`, an explicit token, and its own cleanup methods. Its sandbox handle is separate from platform `client.sandbox` session IDs. Code using both packages needs Node 22+ to meet the Sandbox SDK requirement.

In an app deployed inside a sandbox, keep the platform SDK and its token in the
server process. Keep tokens out of browser JavaScript, including apps accessed
through preview URLs.

## CLI: platform commands from a terminal

Use the CLI when the integration point is a terminal, CI job, or Trickest sandbox.
The command grammar is `trickest <noun> <verb>`.

```bash
export TRICKEST_TOKEN='YOUR_TOKEN'

trickest --output json auth status
trickest workflow ls --all --filter "discovery"
trickest workflow use 'WORKFLOW_ID'

trickest run execute --watch
trickest database query 'severity = "high"' --table findings --limit 10
trickest memory search "discovery scope"
```

The CLI adds interactive auth,
active context, YAML workflow apply/patch, graph analysis, `--watch`, and
machine-readable JSON output on top of the platform APIs.

References: [CLI overview](/docs/developer-tools/cli), [CLI runs](/docs/developer-tools/cli/runs), [CLI database](/docs/developer-tools/cli/database).

## MCP: tools for coding agents

Use MCP when Claude, Claude Code, Cursor, Codex, or another MCP-compatible
assistant needs to call Trickest tools.

Trickest MCP is a **hosted** Streamable HTTP service at
`https://api.trickest.io/mcp`. There is no npm package and no self-hosted binary
for customers. Two ways in:

- **Sign in.** Clients that run an OAuth flow (Claude on the web and desktop,
  Claude Code, Codex) open a Trickest consent page the first time; you approve,
  and the connection appears under [Settings > Credentials](https://trickest.io/settings/credentials)
  where you can revoke it.
- **API token.** Clients that only take headers (Cursor, CI, custom clients)
  send your API token as `Authorization: Token <token>`.

```json
{
  "mcpServers": {
    "trickest": {
      "url": "https://api.trickest.io/mcp",
      "headers": {
        "Authorization": "Token <YOUR_TOKEN>"
      }
    }
  }
}
```

The server exposes 40 tools: status, library search, workflow graph reads, node
edits, connections, run execution and waiting, output reads, Live Table queries,
variables, memory, and a dispatch layer for every other CLI command. Each tool
carries read, write, or destructive annotations, so your client can allow reads
and prompt on the rest. The [MCP page](/docs/developer-tools/mcp) has per-client
setup, the sign-in flow, permissions, and limits; the
[tool reference](/docs/developer-tools/mcp/tools) lists every tool.

<Warning>
  There are two MCP directions on the platform. The hosted `/mcp` endpoint lets
  external agents drive Trickest. The in-app Trickest agent can also consume
  remote MCP servers registered in Settings. Those are separate systems.
</Warning>

## Coding agents: one-command connect

MCP is not the only path. The installer at `trickest.io/integrate` installs the
Trickest skill into your local coding agent (Claude Code, Cursor, or Codex) and
makes sure the `trickest` CLI is installed and signed in. The skill then drives
the CLI from your agent's shell, with no MCP setup required:

```bash
curl -fsSL https://trickest.io/integrate | sh

# or name the client explicitly:
curl -fsSL https://trickest.io/integrate | sh -s -- --client claude-code   # or: cursor | codex

# headless / CI (no browser): export a token first, auth is then non-interactive
export TRICKEST_TOKEN='YOUR_TOKEN'
curl -fsSL https://trickest.io/integrate | sh
```

Get a token from **Settings > Developer > API Token**. Useful flags: `--dir <path>`
sets the project directory for Cursor and Codex, and `--no-cli` installs the
skill only. When no fleet can run workflows, the installer offers to enroll the
current device as a self-hosted worker (`--attach` / `--no-attach` to decide up
front).

## Skills: repeatable playbooks

Skills are markdown files that teach the Trickest agent what to do. They do not
execute by themselves. A skill tells the agent which `trickest` commands, SDK
methods, workflow edits, Live Table queries, or sandbox files to use.

The agent loads built-in skills into sessions. Save user skills to a vault to
reuse them across sessions. The agent makes them available in the sandbox at:

```text
.trickest/skills/<key>/SKILL.md
```

Use skills for repeatable work:

- A discovery workflow builder that chooses library tools, connects nodes, runs the
  graph, and checks outputs.
- A database/TQL guide that reminds the agent TQL is filter-only.
- An app-builder guide that keeps `@trickest/sdk` server-side when generating a
  dashboard over Live Tables.

Current caveats:

- Vault skill management through the SDK is not available to standard accounts.
  Installing a local coding-agent skill is a separate operation.
- Use the integration installer for local coding agents; there is no public
  `@trickest/skills` package.
- Installing a skill into a sandbox by writing `SKILL.md` is session-local unless
  it is saved to the vault.
- A skill fetched from another ecosystem may assume Claude Code features that are
  not present in the Trickest sandbox.

## Recommended setup

Choose the steps that match your integration. You do not need to install or
configure every option.

<Steps>
  <Step title="Start with a token">
    Create or copy a Trickest API token, then export it as `TRICKEST_TOKEN` in
    the environment where your SDK or CLI runs. MCP clients that sign in do not
    need it.
  </Step>
  <Step title="Use the SDK in code">
    Build application logic with `TrickestClient`. Keep the token server-side
    and use typed namespaces for workflows, runs, Live Tables, sessions, memory,
    and skills.
  </Step>
  <Step title="Use the CLI for shell automation">
    Install or bake in the `trickest` binary for CI and sandbox agents. Prefer
    `--output json` when another tool will parse the result.
  </Step>
  <Step title="Expose Trickest to coding agents with MCP">
    Add the hosted MCP endpoint to Claude, Claude Code, Cursor, Codex, or another
    MCP client. Sign in from the client, or pass the API token in its
    authorization header. Keep write and delete tools on ask.
  </Step>
  <Step title="Add skills for repeatable work">
    Store reusable playbooks as skills so the agent knows which tools to use
    before it edits or runs anything.
  </Step>
</Steps>

---
_Markdown source of https://trickest.com/docs/developer-tools/sdk/agent-integrations._