Agent Integrations

Trickest exposes the same execution layer through four integration paths. Use the SDK when you are writing TypeScript, the CLI when a human or agent is in a terminal, MCP when an external coding agent needs tools, and skills when you want the agent to follow a repeatable playbook.

Which path to use#

SDK: typed calls from your code#

Use the SDK when you control the runtime and want typed TypeScript instead of a shell command.

import { TrickestClient, runTurn } from '@trickest/sdk'
 
const client = new TrickestClient({
  token: process.env.TRICKEST_TOKEN,
  baseUrl: process.env.TRICKEST_BASE_URL ?? 'https://trickest.io',
})
 
const run = await client.runs.execute(workflowId, {
  inputs: { domain: 'example.com' },
})
 
const table = await client.database.resolveByName('findings', workflowId)
const findings = await client.database.query(
  table.id,
  'severity = "high"',
  { limit: 100 },
)
 
const session = await client.sessions.create(vaultId, 'Discovery review')
const handle = await client.sessions.handle(session.id, vaultId)
const turn = await runTurn(handle, {
  prompt: 'Summarize the high-severity findings',
})

Important constraints:

• TRICKEST_BASE_URL is the web app origin, for example https://trickest.io. It is not a raw backend URL.
• client.database.query() takes TQL, a filter expression. It is not SQL.
• Agent UI should use SessionHandle.subscribe() and subscribeStreaming(). runTurn() is for headless scripts.
• Never expose TRICKEST_TOKEN in a browser client component. Proxy through a server route.

Read more: Client setup, Sessions, Database.

CLI: terminal shape for the same platform#

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

export TRICKEST_TOKEN=<token>
 
trickest auth status --output json
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.

Read more: CLI overview, CLI runs, CLI database.

MCP: tools for coding agents#

Use MCP when Claude Code, Cursor, Codex, or another MCP-compatible assistant needs to operate Trickest as 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.

{
  "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. It is designed to give agents safer, typed access than raw shell commands while preserving the CLI's workflow behavior.

Current caveats:

• Hosted OAuth MCP registration is planned; current config uses 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:

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-api-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: playbooks, not plugins#

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, WorkflowApply edits, Live Table queries, or sandbox files to use.

Built-in skills are loaded automatically into agent sessions. Durable user skills are vault-scoped and materialize into the sandbox at:

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

• @trickest/skills is not yet available as a public 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#