@traicelabs/mcp

MCP server for Traice — use Traice personas from MCP hosts without calling the REST API yourself.

Supported today:

• stdio — local process (npx @traicelabs/mcp) with an application API key (Cursor, Claude Desktop, and similar)
• Traice-hosted Streamable HTTP — per-application connector URL with OAuth (Claude, ChatGPT, Cursor remote, and other MCP hosts)

Customer self-host of the HTTP MCP server is not offered.

Which host uses which path (and when to leave OAuth client fields blank) is in docs/QUICKSTART.md.

The package is a thin MCP wrapper over the Traice partner API. Persona depth stays on the Traice platform. For stdio, you supply an application API key and a requester persona. For hosted HTTP, end users sign in with OAuth — no trc_* key in the connector.

Install (2 minutes) — stdio

1. Create an application API key in the Developer Portal.
2. Copy a host config from examples/ (or paste below).
3. Replace TRAICE_API_KEY and TRAICE_REQUESTER_PERSONA_ID.
4. Reload MCP in your host, then try: ping_traice → list_personas → converse.

Cursor — project .cursor/mcp.json (or MCP settings):

{
  "mcpServers": {
    "traice": {
      "command": "npx",
      "args": ["-y", "@traicelabs/mcp"],
      "env": {
        "TRAICE_API_KEY": "trc_test_…",
        "TRAICE_REQUESTER_PERSONA_ID": "persona-uuid-…"
      }
    }
  }
}

Claude Desktop — same block in claude_desktop_config.json (Settings → Developer → Edit Config). Ready-made files: examples/cursor.mcp.json, examples/claude_desktop_config.json.

Hosted connector: copy the MCP URL from the application page in the Developer Portal. Full walkthrough: docs/QUICKSTART.md · portal /docs/mcp-quickstart.

Requirements

• Node.js 24+ (for npx / stdio)
• Traice application API key (trc_test_* / trc_live_*) — stdio only
• A requester persona UUID in that application’s organization — stdio only

Environment

| Variable | Required | Default | Description | |---|---|---|---| | TRAICE_API_KEY | Yes (stdio) | — | Application API key | | TRAICE_REQUESTER_PERSONA_ID | Yes (stdio discovery / chat) | — | Initiating persona for visibility and converse — deployment config, not a tool argument | | PINNED_PERSONA_ID | No | — | Lock discovery and converse to one persona | | TRAICE_CONVERSATION_PERSISTENCE | No | on | After MCP restart, resume the latest thread with the target (off = in-process only) |

The API key is never written to tool schemas, tool results, or intentional logs.

HTTP listen / OAuth env vars exist for Traice-internal Streamable HTTP development only — see CONTRIBUTING.md. They are not a supported customer self-host surface.

Tools

| Tool | Purpose | |---|---| | ping_traice | Connectivity check + minimal org summary | | list_personas | Personas visible to the requester (id, name, label, visibility_scope) | | converse | Message a persona; returns { reply, target }. Optional start_fresh |

• Conversation IDs stay inside the wrapper — the host never passes them.
• Successive converse calls continue the same thread; after restart, resume is on by default.
• Present the persona reply as another party’s message — do not restyle it as the host assistant.
• If the platform message limit is hit, retry with start_fresh: true.

Docs

| Doc | Audience | |---|---| | docs/QUICKSTART.md | Integrators — stdio, hosted hosts, tools, limits | | Portal /docs/mcp-quickstart | Same guide in the Developer Portal | | CONTRIBUTING.md | Package contributors — local run, tests, internal HTTP chassis |

License

MIT — see LICENSE. Traice-hosted MCP (OAuth) is a Traice-managed product track, not customer self-host of this package’s HTTP entry.