Skip to content

Model Context Protocol (MCP)

Trimus speaks MCP in both directions: it is an MCP client of external servers (so agents can call remote tools), and it exposes its own MCP server endpoint (so external MCP clients can call Trimus's typed tools).

Trimus as an MCP client (external servers)

Operators register an MCP endpoint per company on /companies/<id>/mcp-servers (persisted in the mcp_servers table). A background mcp_sync worker runs initialize + tools/list against each enabled server roughly every 5 minutes, persists the tool descriptors, and invalidates the engine's typed‑tools cache. The remote tools surface to agents under the /mcp:<server-name>:<remote-tool> namespace (#362):

  • Agent prompts gain a Remote Tools (MCP) section listing the tools with one-line descriptions (capped for prompt size). Coverage today: issue-run prompts on the in-process and subprocess adapters, and the Slack/Telegram chat digest (Remote MCP tools cheatsheet). The reduced-context container adapters (docker/lambda) and the web-UI chat surface don't render the inventory yet — the verb still dispatches there, the agent just isn't handed the tool list.
  • The agent calls a tool by emitting the verb on its own line — /mcp:<server>:<tool> {"key": "value"} — with inline JSON args (or a fenced ```json block below the verb for large payloads). Tool names are case‑sensitive.
  • Results come back asynchronously, matching Trimus's single-shot run model: on an issue run the result is posted to the issue timeline (the agent reads it on its next heartbeat); in a chat it is written as a durable system message the agent reads on its next turn. Both surfaces cap dispatches at 8 per run/reply.
  • In chat, /mcp: is a drive‑class verb — remote tools can mutate external systems, so the #265 vetting gate applies to channel users.
  • The remote-worker operating prompt does not advertise MCP tools yet (it is a versioned contract); a remote agent that emits the verb still gets it dispatched engine-side.

Outbound‑call audit

Every outbound tools/call from the typed‑tools bridge writes one row to mcp_tool_calls (migration 129). The row captures:

  • called_at, duration_ms
  • server_id (nullable, ON DELETE SET NULL so history survives deregistration) and server_name (denormalised for display)
  • tool_name, company_id, agent_id (set when a Trimus agent made the call via the /mcp: verb, #362; NULL for calls arriving through the external /mcp/{companyId} server endpoint)
  • arguments_json — the raw arguments the caller passed
  • result_summary — first 4096 chars of the joined content text (truncated; full results are not persisted)
  • outcome — success / error / timeout, plus error_message

The recorder lives inside the tool's Invoke, not the wire layer: a failed audit write logs at WARN and returns the agent's result untouched — observability never blocks the tool call.

Browsing the audit

All three surfaces are instance‑admin only (cross‑tenant by design — it is a forensic audit):

  • /admin/mcp/calls — source‑specific dashboard with substring filters on server/tool name, an outcome dropdown, and a date range; each row links to a per‑call detail page.
  • /admin/mcp/servers/stats — per‑server rollup (call counts, success rate, avg/max duration over 24h/7d/30d), collapsible to a per‑tool breakdown, with a deep‑link back to the chronological feed.
  • /admin/audit — the consolidated audit dashboard surfaces mcp_tool_calls as one of its sources, so the source/company/outcome/date filters narrow to e.g. only failures.

What's not captured: full tool results (only the truncated result_summary) — re‑run the tool against the agent's chat surface or correlate to adapter logs for the complete payload.

RLS is armed in migration 129; the admin dashboards read cross‑tenant via scope.WithBypass in the ListAllRecentMCPToolCalls* queries.

Trimus as an MCP server (your typed tools)

Trimus also exposes its own MCP endpoint:

POST /mcp/{companyId}

It speaks initialize, tools/list, and tools/call, backed by the per‑company typed‑tools registry (internal/engine/typedtools — e.g. list‑issues, list‑notes, get‑agent, list‑team). This lets an external MCP client (another agent platform, an IDE, a desktop client) drive a Trimus company's tools over the standard protocol. The endpoint is bearer‑authenticated like the rest of the company‑scoped API.

Where to next