{
  "markdown": "# truss-agent-mcp\n\nTruss threat intelligence via **[Model Context Protocol](https://modelcontextprotocol.io)** and a terminal assistant — one binary: **`truss-mcp`**.\n\n[![smithery badge](https://smithery.ai/badge/truss-security/truss-mcp)](https://smithery.ai/servers/truss-security/truss-mcp)\n\n[Truss MCP on Smithery](https://smithery.ai/servers/truss-security/truss-mcp)\n\n## Two surfaces\n\n| Surface | Use for | Auth |\n|---------|---------|------|\n| **Remote (recommended)** | Cursor, Claude Desktop, MCP registries | OAuth → [`https://api.truss-security.com/mcp`](https://api.truss-security.com/mcp) |\n| **Local stdio (legacy)** | Air-gap / BYO-key / FilterQL REPL tools | `TRUSS_API_KEY` → REST |\n\nHosted MCP (OAuth, Growth+ gate, five tools) is served by the Truss API. This package ships configs, `validate-remote` / `doctor --remote`, CLI search, and optional local stdio. **Community** accounts cannot consent to hosted MCP.\n\n> **Not on npm yet.** Install from this repo (`npm install -g .`). After publish: `npm install -g @truss-security/truss-agent-mcp`.\n\n## Quick start\n\n```bash\ncd truss-agent-mcp\nnpm install && npm run build\nnpm install -g .\ntruss-mcp doctor --remote --strict-oauth   # OAuth path hosts use\ntruss-mcp init                            # for CLI search / legacy stdio\ntruss-mcp search\n```\n\nNode.js 18+. Binary name **`truss-mcp`** avoids conflict with `@truss-security/truss-sdk`'s `truss` command.\n\n## What you can run\n\n| Command | What it does |\n|---------|----------------|\n| `truss-mcp search` | Guided REPL with live MCP tools (local stdio or remote OAuth token) |\n| `truss-mcp mcp` | Local stdio MCP server (legacy / air-gap) |\n| `truss-mcp init` | Interactive `.env` setup |\n| `truss-mcp doctor` | Validate keys and API access; `--remote` runs hosted OAuth doctor |\n| `truss-mcp validate-remote <url>` | OAuth + MCP doctor (discovery, DCR, PKCE, tools) |\n| `truss-mcp help` | Usage summary |\n\n## Guided search workflow\n\nOne REPL with MCP tools always connected. The assistant classifies your intent and asks before querying Truss API:\n\n1. **Knowledge** — Truss platform, cyber security context, threat background\n2. **Build filter** — draft FilterQL, validate, confirm\n3. **Query** — `run` executes confirmed filter (default **7 days**)\n4. **Format** — `stix` for STIX export; JSON summaries in-thread\n5. **Detection rules** — `detect splunk`, `detect falcon`, `detect cortex` from search results\n\nThe assistant offers next steps explicitly: build a filter, refine it, query Truss API, export JSON/STIX, or generate SIEM/EDR hunting queries.\n\n- Wider windows (`run 30`, `days 30`) may use more API quota\n- Context-only follow-ups (IOC dedupe, reformat) use thread history without re-querying\n\nFull REPL reference: **[guides/truss-cli.md](guides/truss-cli.md)**\n\n## Terminal display (REPL)\n\n`truss-mcp search` uses color-coded, ASCII-bordered output:\n\n- **You** — your message\n- **MCP** — live tool trace (`→ search_threats` on remote, or `→ search_products` on stdio)\n- **Results** — structured product table before the assistant summary\n- **Truss** — assistant reply (cyan), guided offers (yellow), FilterQL blocks (magenta)\n\nControls: `color` / `color on` / `color off` / `color auto` · env `TRUSS_MCP_COLOR` · standard `NO_COLOR=1`\n\n## MCP host (Cursor / Claude) — remote OAuth (recommended)\n\nNo API key in host config. Growth+ Truss account; browser OAuth consent.\n\n```json\n{\n  \"mcpServers\": {\n    \"truss-mcp\": {\n      \"url\": \"https://api.truss-security.com/mcp\"\n    }\n  }\n}\n```\n\nSamples: [config/cursor.mcp.json](config/cursor.mcp.json) · [config/claude_desktop_config.json](config/claude_desktop_config.json) · [guides/client-setup-cursor.md](guides/client-setup-cursor.md).\n\n### Legacy stdio (air-gap)\n\n```json\n{\n  \"mcpServers\": {\n    \"truss-mcp\": {\n      \"command\": \"truss-mcp\",\n      \"args\": [\"mcp\"],\n      \"env\": { \"TRUSS_API_KEY\": \"YOUR_KEY\" }\n    }\n  }\n}\n```\n\nSee [config/cursor.mcp.stdio.json](config/cursor.mcp.stdio.json) and [guides/getting-started.md](guides/getting-started.md).\n\n## Remote MCP OAuth validation (registry gate)\n\nUse as the OAuth + MCP doctor before registry publish or release. After OAuth it **requires** `search_threats` to return at least one Truss product (`id` + `title`). The access token stays **in memory for that process only** unless you pass `--save-token`.\n\n```bash\ntruss-mcp doctor --remote --strict-oauth\n# or:\ntruss-mcp validate-remote https://api.truss-security.com/mcp --strict-oauth\n```\n\nAfter token exchange it prints an **OAuth compatibility checklist** (resource URI, redirects, PKCE S256, issuer match, audience vs MCP resource, `truss_role`), then proves MCP access with real Truss data.\n\nOptions:\n\n```bash\ntruss-mcp validate-remote https://api.truss-security.com/mcp --verbose\ntruss-mcp validate-remote https://api.truss-security.com/mcp --strict-oauth\ntruss-mcp validate-remote https://api.truss-security.com/mcp --save-token /tmp/truss-mcp-token\ntruss-mcp validate-remote https://api.truss-security.com/mcp --token-file /tmp/truss-mcp-token\ntruss-mcp validate-remote https://api.truss-security.com/mcp --port 9877\ntruss-mcp validate-remote https://api.truss-security.com/mcp --no-open\n```\n\n- `--verbose` — HTTP statuses, key headers, truncated bodies (tokens redacted)\n- `--strict-oauth` — exit `2` if the OAuth checklist has WARN/FAIL (even when Truss MCP calls succeed)\n- `--save-token PATH` — write the access token for local replay (mode `0600`; delete after debugging)\n- `--token-file PATH` — skip browser OAuth; reuse a saved token to re-check MCP access + Truss data\n\nOptional automated OAuth data tests (saved token + `TRUSS_RUN_MCP_OAUTH=1`) are documented in [guides/publishing.md](guides/publishing.md).\n\nOfficial listing: [server.json](server.json) (`com.truss-security/truss-mcp`) · Tracker: [guides/registry-submission.md](guides/registry-submission.md) · Internal metadata: [config/mcp-registry.json](config/mcp-registry.json) · Architecture: [docs/05-hosted-mcp-oauth-architecture.md](docs/05-hosted-mcp-oauth-architecture.md)\n\n## Configuration\n\nEnv load order (shell vars win): `~/.config/truss/env` → `~/.truss/.env` → `./.env`\n\n| Variable | Required for | Notes |\n|----------|--------------|-------|\n| `TRUSS_API_KEY` | local `mcp` / stdio `search` | From Truss dashboard (legacy air-gap only) |\n| `TRUSS_MCP_URL` | remote `search` / doctor | Default `https://api.truss-security.com/mcp` |\n| `TRUSS_MCP_OAUTH_TOKEN_FILE` | remote `search` | Bearer token from `validate-remote --save-token` |\n| `LLM_PROVIDER` | search | `anthropic` or `openai` — set via `init` |\n| `LLM_MODEL` | search | Set via `init` |\n| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | search | Per provider |\n\nFull list: [env.example](env.example)\n\n## Documentation\n\n**Guides** — install, REPL, MCP clients, FilterQL examples\n\n- [Getting started](guides/getting-started.md)\n- [Terminal REPL](guides/truss-cli.md)\n- [FilterQL cookbook](guides/filterql-cookbook.md)\n- [Cursor setup](guides/client-setup-cursor.md) · [Claude Desktop](guides/client-setup-claude-desktop.md)\n\n**Reference** — API contract, tools, architecture ([docs/README.md](docs/README.md) — docs 01–06)\n\n## Development\n\n```bash\nnpm install && npm run build\nnpm test\nnpm run truss:search    # from source without global install\n```\n\n**Contributors / AI agents:** see [AGENTS.md](AGENTS.md) for repo operations and conventions.\n\nPublish: [guides/publishing.md](guides/publishing.md) · Changes: [CHANGELOG.md](CHANGELOG.md)\n\n## Related\n\n- [@truss-security/truss-sdk](https://www.npmjs.com/package/@truss-security/truss-sdk) — API client\n- [truss-agent](https://github.com/truss-security/truss-agent) — scheduled webhook delivery\n- [Truss docs](https://github.com/truss-security/truss-docs) — public API / SDK documentation\n\nMIT\n",
  "bytes": 7767,
  "sha": "b602dacc58bd00557219bac65578617dfbc175cf3889253023f140d4510b4f0d",
  "repo_slug": "truss-security/truss-agent-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_truss_security_truss_mcp_45b69117/readme"
}