---
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`.
</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 Code, Cursor, or Codex" icon="robot">
    Point your MCP client at the hosted endpoint `https://api.trickest.io/mcp`
    with an API token (`Authorization: Token …`). The agent then discovers and
    calls workflow/run 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 Code, Cursor, Codex, or another MCP-compatible assistant
needs to call Trickest tools.

Trickest MCP is a **hosted** Streamable HTTP service in production
(`https://api.trickest.io/mcp`). There is no npm package and no self-hosted
binary for customers. Point your client at the URL and pass your Settings API
token with the `Token` scheme (same as the platform API). `Bearer` still works
for JWTs and existing configs.

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

The server exposes tools for status, library search, workflow graph reads, node
edits, connections, run execution and waiting, output reads, and post-run
verification. Each tool exposes a structured input schema. Review tool permissions in the client where you connect it.

<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>

Current caveats:

- Authenticate with a static `Authorization` header.
- There is no `trickest mcp` CLI subcommand and no customer-installable MCP
  package. Use the hosted URL only.

## 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 (or paste it into the MCP client
    `Authorization` header).
  </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">
    Configure the hosted MCP endpoint in Claude Code, Cursor, Codex, or another
    MCP client, and pass the API token in its authorization header.
  </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._