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, 'Recon 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 "recon"
trickest workflow use <workflow-id>
 
trickest run execute --watch
trickest database query 'severity = "high"' --table findings --limit 10
trickest memory search "recon scope"

The CLI is also the layer the MCP server uses today. It 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.

The v2 MCP server lives in packages/mcp and exposes workflow/run tools over stdio. It shells out to the trickest binary, so the CLI must be built and available on PATH or provided through TRICKEST_CLI.

{
  "mcpServers": {
    "trickest": {
      "command": "node",
      "args": ["/path/to/packages/mcp/dist/index.js"],
      "env": {
        "TRICKEST_TOKEN": "<token>",
        "TRICKEST_BASE_URL": "https://trickest.io"
      }
    }
  }
}

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:

• There is no trickest mcp CLI subcommand yet.
• The MCP server currently wraps the CLI. It does not call the SDK directly.
• Hosted OAuth MCP registration is planned, but current server config uses static environment variables or headers.

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 recon 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 private in v2.
• 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