Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Guides/MCP Integration

MCP Integration

Trinity's MCP server exposes 185 tools across 41 modules for agent orchestration via the Model Context Protocol, enabling programmatic control from Claude Code, other MCP clients, or agent-to-agent communication. 180 of them are the operator tool set; three consumption-only tools are visible only to connector keys, and two sign-in tools are registered only when inline email auth is enabled. A few operator tools are enterprise-gated and return "disabled" (or a not available result) where not entitled.

From Zero to Deployed AI Agent — MCP setup

Apr 2026

Overview

The Model Context Protocol (MCP) is an open standard for tool-based AI integrations. Trinity implements an MCP server using FastMCP with Streamable HTTP transport on port 8080. API keys authenticate access: they are generated under Settings → MCP Keys and sent via the Authorization: Bearer header.

Agent-scoped keys are keys Trinity mints for each agent automatically (its Trinity access key, visible under the agent's Settings › Integrations) so the agent can call the platform as itself. You do not create these by hand; the keys you create yourself are user-scoped, ops, or portal_delegate — see Authentication.

Authentication

MCP API Keys page showing auto-generated agent keys with usage stats and connection snippet
1

Go to Settings → MCP Keys.

2

Click Create API Key, name it, and choose a Key scope — Standard for your own use, or one of the bounded scopes.

3

Copy the generated key (prefixed trinity_mcp_*).

4

Use the key as a Bearer token in the Authorization header.

Signing in with an email code instead of a key

If your admin has enabled inline authentication, you can connect with no API key at all and sign in from inside your MCP client:

1

Connect with a keyless connector configuration.

2

Call request_login(email) — a 6-digit code is emailed to you.

3

Call verify_login(code).

You can then use the exposed skills of every agent shared with that email. This mirrors the /login flow that Telegram and WhatsApp already use.

Two things to know: the login binds a session, not a key — nothing is written to disk and you are never handed a trinity_mcp_* token. And MCP sessions are per-connection, so restarting your client means logging in again.

Inline authentication is off by default (MCP_INLINE_AUTH_ENABLED). Operators enabling it should set INTERNAL_API_SECRET explicitly rather than relying on its fallback.

Connecting from Claude Code

Add Trinity as an MCP server in your Claude Code configuration:

{
  "mcpServers": {
    "trinity": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Which URL to use

•Local install: http://localhost:8080/mcp — the MCP server's own published port. On a fresh install that port is published on 127.0.0.1 only, so it answers on the Trinity host itself.
•Production install behind the frontend (nginx): https://your-domain.com/mcp. The frontend proxies /mcp to the MCP server, so an install that exposes only ports 80/443 (a firewalled host, a one-click cloud image) still serves MCP without opening port 8080.

Either URL answers an outside client only while External MCP accessis on — see below. A fresh install, local development included, starts with it off: turn it on once before Claude Code on your laptop connects.

The URL Trinity advertises — in the MCP Keys page's connection snippet and in an exposed agent's Copy connection config — is auto-detected from the request. A request that came through a proxy (the bundled frontend always sends X-Forwarded-Proto; a Cloudflare Tunnel does too) gets <origin>/mcp, with no :8080, whatever the scheme — the frontend serves /mcp on the same origin. A request that reached the backend directly gets the raw port: http://127.0.0.1:8080/mcp when MCP_BIND_ADDRESS is set (the port answers only on that address), otherwise http://<host>:8080/mcp. If you run your own proxy, configure it to send X-Forwarded-Proto (see Public Access). When the detected URL is still wrong, an admin sets the real one under Settings → MCP Keys → MCP Server URL (it must end in /mcp); Auto-detect there shows what would be advertised otherwise.

External MCP Access

External MCP access decides whether clients outside the Trinity server may reach /mcp at all. It is off on a fresh install. Agents running on the instance are never affected: they connect to the MCP server over the Docker network and keep working whatever the switch says.

•The switch: Settings → MCP Keys → External MCP access (admins). Everyone else sees the current state on the same page. While it is off, the page shows a notice in place of the connection snippet, and an exposed agent's Copy connection config is disabled with the reason.
•Precedence: a value saved in Settings wins, on or off. With nothing saved, MCP_EXTERNAL_ACCESS=true in the environment turns it on. Otherwise it is off. The page says which of the three is in effect, and Clear removes the saved value so the environment or the default decides again.
•Upgrades: an install that already had users when it upgraded keeps external MCP access on — the upgrade saves that value for it once. Only new installs start off.

Who counts as outside. The MCP server looks at where each connection comes from. Loopback inside its container and agents on the agent network are inside. Everything else is outside — the bundled web frontend's /mcp, a Cloudflare Tunnel, a reverse proxy on the host (Caddy included), and any client using the published port, even from the Trinity host itself. The only ways in from outside are the frontend's /mcp and the published :8080 port, and the switch covers both. Docker daemons with IPv6 enabled are not supported by this check: their peers read as outside.

What a refused client sees. Every request on the MCP port — /mcp in any spelling, the legacy /sse + /messages transport, any other path — is answered with a JSON-RPC error rather than a dropped connection, except DELETE /mcp (so a client can still close its session) and the /health probe:

StatusX-Trinity-RefusalMeaningWhat to do
403external_mcp_access_offExternal MCP access is off on this instanceAn admin turns it on under Settings → MCP Keys
503 (with Retry-After: 5)external_mcp_access_unverifiedThe MCP server could not get the setting from the backend yet — it is still starting, or INTERNAL_API_SECRET is not setRetry shortly; if it persists, check the backend and that INTERNAL_API_SECRET is set

The JSON-RPC error code is -32003 for both. Only GET or HEAD /health (the container's own health probe) and DELETE /mcp are ever let through while the switch is off; there is no path or transport on the port that bypasses it.

The published port — MCP_BIND_ADDRESS. This .env key is the interface the MCP server's :8080 port is published on. Fresh installs set 127.0.0.1, so the port answers only on the Trinity host and outside clients use the frontend's /mcp. An upgraded .env that does not carry the key keeps publishing on every interface, as before. Empty means every interface. The key is read when the containers are created, so change it in .env and recreate the stack.

Tool Categories

The MCP server organizes its tools into these modules:

ModuleToolsDescription
agents.ts22Agent lifecycle, credentials, SSH, local deploy, GitHub sync, per-agent PAT (get_agent_github_pat_status, set_agent_github_pat), runtime-data export/import, compatibility report, get_agent_info (an agent's template metadata and capabilities) and list_templates (the template IDs create_agent accepts). create_agent can fork a template into a repository you own (import_intent: "fork" with a fork_to_own block) — never a token argument. The fork spends your saved personal GitHub token only from a signed-in session, so over MCP it is refused FORK_PAT_REQUIRED for every key; create the fork in the web UI. list_agents, get_agent and get_agent_info return each agent's kind (agent or deployment, null when unknown). rename_agent, initialize_github_sync, set_agent_github_pat, inject_credentials and export_credentials are a person's: shown only to your own user-scoped key. import_credentials takes a signed-in session and is shown to no key; get_credential_encryption_key is shown to user-scoped and system-scoped keys, and the backend admits an administrator only
chat.ts4chat_with_agent, get_chat_history, get_agent_logs, fan_out — chat and parallel dispatch, all gateway-timeout safe
executions.ts5list_recent_executions, get_execution_result, get_fan_out_result, get_agent_activity_summary, search_executions — execution queries, polling for async tasks and fan-out batches, activity monitoring; search_executions needs a matching entitlement and is never offered to agent keys
schedules.ts8Schedule CRUD (including retries, post-run validation and Workspace delivery) and execution history
skills.ts14Skill management and assignment (including skill sets: list_skill_sets, unassign_skill_set), the per-agent skill gate map (list_skill_gates, set_skill_gate, clear_skill_gate — see Approvals), plus the skill-runner tools run_skill and list_runnable_skills (enterprise-gated — return "disabled" in community builds)
skill_sources.ts6Skills-library source management — list_skill_sources, register_skill_source (idempotent on the repository URL), update_skill_source, delete_skill_source, sync_skill_source, sync_skill_library. Admin only: shown to user-scoped and system-scoped keys, never to agent-scoped or connector keys; the backend admits an administrator only
tags.ts5Agent tagging
systems.ts6deploy_system, list_systems, restart_system, get_system_manifest, teardown_system (needs a matching entitlement; previews by default), apply_system (reconciles a live instance to a manifest; previews by default; a person's key only) — see System Manifest
subscriptions.ts6Subscription management. assign_subscription takes a signed-in session and is shown to no key; clear_agent_subscription is shown only to your own user-scoped key
monitoring.ts4get_fleet_health, get_fleet_sync_audit, get_agent_health, trigger_health_check — fleet health, git sync health, and the fleet sync audit (see Monitoring)
metrics.ts4record_metrics, get_metrics, get_objectives, refresh_metric_definitions — the calling agent's declared business metrics and objectives (see Dynamic Dashboards)
nevermined.ts6Payment configuration, payment history, agent spending and delegation revocation. configure_nevermined takes a signed-in session and is shown to no key; toggle_nevermined and revoke_agent_delegation are shown only to your own user-scoped key
notifications.ts1send_notification — agent-to-platform notifications (alert, info, status, completion, question)
events.ts4Agent event pub/sub
docs.ts2get_agent_requirements, ask_trinity — agent documentation and grounded Q&A about Trinity
channels.ts2Channel group discovery + proactive group messaging (Telegram and Slack)
messages.ts1send_message — proactive message to a person, addressed by role
voice.ts1send_voice_reply — speak one reply of the current channel turn as a voice note (see Voice Replies)
files.ts1share_file — publish file to a signed download URL
memory.ts2write_user_memory — per-user memory blob, isolated server-side; search_memory — search the agent's retrieval memory on demand
decisions.ts3record_decision, list_seat_decisions — record why something was approved, deferred or killed for the seat an agent serves, and read that seat's standing decisions back; get_autonomy — what this companion may do unprompted for that seat, and why not where it may not
loops.ts3run_agent_loop, get_loop_status, stop_loop — sequential bounded task loops
voip.ts1call_user — outbound phone call (flag-gated, requires a per-agent voice binding)
operator_queue.ts7list_operator_queue, get_operator_queue_item, respond_to_operator_queue, get_my_ask, ask_operator, withdraw_ask, ask_for_credential — read and resolve Operating Room queue items; an agent raises its own asks, reads them back, and withdraws one that no longer needs an answer; ask_for_credential asks the person in the conversation for a secret by name, which they type into a masked field in their Workspace. respond_to_operator_queue is shown only to your own user-scoped key, because only a person answers an item
reminders.ts3set_reminder, list_reminders, cancel_reminder — durable one-shot deferred self-triggers
rooms.ts5create_room, list_rooms, read_room, post_to_room, close_room — multi-agent rooms (see Rooms). close_room is shown only to your own user-scoped key, because only a person moderates a room
canvas.ts5set_canvas, patch_canvas, get_canvas, list_canvases, clear_canvas — the agent's durable render surface in the Workspace (see Agent Canvas)
git.ts6Deterministic git operations — status, sync, log, pull, sync-state, and the destructive reset-to-main recovery
pipelines.ts2Read-only introspection of an agent's self-published pipelines
reports.ts3report, list_reports, get_report — publish a structured report and read reports back (see Agent Reports)
a2a.ts7A2A management plane — per-agent exposure and card and the inbound allow-list (entitlement-gated), plus the outbound endpoint registry register_a2a_endpoint / list_a2a_endpoints / remove_a2a_endpoint (every edition; admin, human-only); register_a2a_endpoint takes auth_scheme (bearer, the default, or aauth). See A2A Protocol
aauth.ts2request_person_token, call_aauth_resource — prototype AAuth legs (person-token binding, allow-listed resource calls); always registered, agent-scoped key only, answer aauth_disabled: true while the AAuth or prototype switch is off. See A2A Protocol
a2a_call.ts2call_a2a_agent, get_a2a_task — task a registered external A2A agent by endpoint name and poll it
credential_vault.ts2list_available_credentials, fetch_credential — pull a granted vault credential by name at runtime (see Credential Management)
projects.ts17Tools for agents working on Workspace projects (enterprise-gated; where unavailable they return a result that says so)
platform_files.ts4list_platform_files, read_platform_file, write_platform_file, remove_platform_file — list, read, write and remove text files in a file space the calling agent works in (enterprise-gated; where unavailable they return a result that says so)
assignments.ts1get_agent_assignments — read who an agent works for (read-only; degrades to a not-available result where unsupported)
permissions.ts2get_agent_permissions, get_agent_capability_grants — read an agent's permission edges (the agents it may call) and its self-change permissions; read-only, granting stays in the UI. An agent key reads edges for itself, an agent it has an edge to, or one it spawned, and grants only for itself or an agent it spawned
member_progress.ts1set_member_progress — the member's assistant agent reports a step of the member's setup progress card; agent-scoped key, for itself only
connector.ts3list_playbooks, run_playbook, ask — the consumption-only set a connector key sees; operator tools stay hidden from connector keys
auth.ts2request_login, verify_login — registered only when inline email auth is on, advertised only to keyless sessions

Dedicated Agent Tools (Expose via MCP)

Agent Settings tab: the Expose via MCP toggle with the resolved chat_with_<slug> tool name, and the Connect an external client panel with its Copy connection config button

An owner can publish an agent as its own first-class MCP tool. Under the agent's Settings › Integrations › Programmatic access, the Expose via MCP section has a toggle; when enabled, the MCP server registers a dedicated chat_with_<slug>tool (the slug is derived from the agent name, with a short suffix on name collisions — the resolved tool name is shown next to the toggle).

•No restart needed — the MCP server picks up the change on its next poll, and connected MCP clients see the tool appear (or disappear) within a few seconds.
•The tool behaves exactly like chat_with_agent with the agent name pre-filled, including idempotency and timeout handling.
•Exposure publishes the tool, not access: callers still need ownership or a share to actually chat with the agent.
•While exposure is on, the same panel shows Connect an external client: Copy connection config mints (or reuses) a connector-scoped key for this agent and copies a ready-to-paste .mcp.json. An existing key is never shown again — Regenerate & copy embeds a fresh one.
EndpointMethodDescription
/api/agents/{name}/mcp-exposedGETExposure flag + the resolved tool_name
/api/agents/{name}/mcp-exposedPUTToggle exposure ({"enabled": true}, owner-only)

Each Agent's Own MCP Key

Every agent carries its own agent-scoped key, injected into its container so it can call Trinity's MCP server. That key is what makes the agent-to-agent permission matrix apply — a container carrying a user-scoped key would operate with the owner's identity and bypass the matrix entirely.

Settings › Integrations › Programmatic access › Trinity access keysurfaces this key so you can see and repair it. You never see the secret itself — only metadata and a health state:

StateMeaning
activeHealthy and in recent use
never_usedThe key exists but the agent has never authenticated with it
staleThe key hasn't been used since well before the agent's last execution — the agent is probably authenticating as something else
missingNo active agent-scoped key exists for this agent
env_absentThe container has no Trinity MCP key configured
env_mismatchThe container's key doesn't match any active key for this agent
exemptThe system agent, which uses a system-scoped key by design

Two actions:

•Check what the container is using (Re-check afterwards) runs a one-shot probe inside the container and reports what its configuration actually contains — including whether it is carrying a foreign user key, another agent's key, or a duplicate entry. A stopped agent degrades to "unavailable" rather than erroring.
•Regenerate key (Issue a key when none exists) rotates the key: a new one is minted, delivered to the container, and the superseded keys are deleted. A running agent is rebuilt to pick it up; a stopped agent is updated in the database and stays stopped. No plaintext is ever returned.

Trinity also self-heals: if an agent starts with a missing or mismatched key, the start path re-mints and re-injects one automatically.

These routes are owner-only and reachable only from an interactive (browser) session — API keys of any scope are rejected, because rotating a credential should not be doable with the credential itself.

EndpointMethodDescription
/api/agents/{name}/mcp-keyGETKey metadata and health state (never the secret)
/api/agents/{name}/mcp-key/verifyPOSTProbe the container's actual configuration
/api/agents/{name}/mcp-key/regeneratePOSTRotate and deliver a new key

Sending Once Across Runs

A recurring agent's runs are separate executions, so the next run can repeat what the last one already told someone. send_message, send_group_message (Telegram and Slack) and call_user take an optional idempotency_key — a stable name for what you are telling them, such as gcp-ceiling-correction (up to 200 characters: letters, digits, _ . : / -) — and an optional idempotency_ttlin seconds (60–86400, default 86400).

•Two sends with the same agent, recipient and key inside the TTL deliver once, from any run. The message text is never part of the key.
•A suppressed send returns success: true, sent: false, suppressed_by: "idempotency_key" with first_sent_at and first_execution_id. Record it; do not resend under a new key.
•A 409 means another run is sending the same key right now. Retry with the same key.
•Change the key when the information changes.
•A send that fails releases the key, so a retry can deliver.

Suppressed sends are written to the audit log. For a message or group message, a system row labelled Trinityis added to the first send's conversation. Calls without a key behave as before.

Refused Calls

When a tool refuses a call because the caller may not reach the target agent, it returns a result rather than a transport error: {"error": "Access denied", "reason": "..."} (some tools also carry success: false). When an agent-scoped key names an agent it has no permission for, chat_with_agent, fan_out and run_agent_loop give the reason Permission denied: Agent '<caller>' is not permitted to communicate with '<target>'. Tools addressed by an id rather than an agent name — get_loop_status and stop_loop — answer a uniform Loop '<id>' not found or not accessible instead, so the reply never reveals whose loop it is.

Every refusal is recorded in the audit log as a refusal, not as a successful call: the mcp_operation entry carries success: false, denied: true, and the reason. A backend 403 that surfaces through a tool is marked denied too. A failure a tool returns rather than raises is recorded as a failure as well: apply_system and teardown_system log a refused or failed run (a 409 refusal report, a retryable 503, a lost connection) as success: false with a short error and no denied flag, while the JSON you receive is unchanged. See Audit Trail → Refused MCP calls.

Receipts

A receipt is what a chat tool returns when it has handed the work to the agent but cannot hand you the reply: an execution_id and a status of accepted (an async call), queued (the agent was at capacity, or it is a pull-mode agent, which queues every task for its workers) or queued_timeout (the call outlived MCP_CHAT_TIMEOUT_MS, default 25 s, or the platform's own wait, and the run is still going). The work is running. Read its outcome with get_execution_result(agent_name, execution_id) and never re-send the same message; the receipt's message says exactly that.

When the caller is an agent serving a Slack, Telegram or Workspace conversation, a receipt can also carry report_back:

•report_back: "requested" — when the delegated run ends, success or failure, it posts its outcome into that conversation; an informational report_back_note reminds the caller that this is best-effort. This is on by default for async delegation (parallel=true, async=true) and for a sequential call (parallel=false) that ends in a queued_timeout receipt: the platform attaches the report only at the moment it hands back the receipt, so a call that answered inline never posts a second "done".
•report_back: "off" with report_back_reason: "not_armed" — the platform could not attach a report to this run (or, when the caller named its own execution_id, the agent was busy and nothing ran); read the outcome with get_execution_result.
•A sequential call that answers inline carries no report_back fields; when the caller named its own execution_id, it says off / answered_inline — you have the reply, nothing more will be posted.
•Pass execution_id="manual" to turn report-back off for one call; MCP_REPORT_BACK_ENABLED=false on the MCP server turns it off everywhere.

requested means a report was attached, not a guarantee that a note lands — a conversation can refuse such notes. See Agent Network for the delegation pattern.

Key Tools Worth Knowing

ToolWhy it exists
chat_with_agentSend a message to another agent. Gateway-timeout safe in every sync mode — sequential chat (parallel=false) and the sync task route (parallel=true, async=false) alike: if the call exceeds MCP_CHAT_TIMEOUT_MS (default 25s), it returns {status: "queued_timeout", agent, execution_id, message} so the caller polls get_execution_result instead of duplicate-queueing the request. The receipt is only issued when the running execution can be attributed to your call unambiguously; otherwise the error says so and names list_recent_executions. Calls carry a deterministic idempotency key, so an identical re-send dedupes server-side and answers with the original execution_id, marked "idempotent_replay": true, while that run is live or has succeeded — a reworded re-send is a new call and dispatches a second execution. After a confirmed failed or cancelled outcome, the identical re-send starts a new run instead (a lease_expired failure first waits out the agent's timeout + 5 minutes). idempotent_replay is positive evidence only: its absence does not prove a fresh run. For work you know will outlive the gateway, use parallel=true, async=true from the start. A receipt means the work is running: an execution_id in place of the reply (accepted, queued or queued_timeout) proves the call arrived, and every receipt ends with Do not re-send: read the outcome with get_execution_result(…). From an agent serving a conversation, a queued_timeout receipt on a sequential call also reports the run's outcome back into that conversation — see Receipts. The tool's description teaches callers this delegation contract verbatim, as does every chat_with_<agent> tool. See Agent Network for the async pattern.
fan_outDispatch N independent tasks to an agent in parallel and collect all the results. Gateway-timeout safe: a batch runs longer than any single task in it, so this is the tool most likely to outlive the 25s ceiling — when it does, it returns {status: "fan_out_timeout", agent, fan_out_id, execution_ids, task_count, message} and the batch keeps running. Poll get_fan_out_result(agent_name, fan_out_id). Re-sending the identical call is deduplicated server-side and answers with the same batch; rewording it dispatches all N tasks again. For a batch you know will run long, pass async_mode: true: the tool returns {fan_out_id, status: "accepted"} at once and you poll. timeout_seconds bounds only the wait — tasks still open at the deadline report running and keep going. See Fan-Out.
get_fan_out_resultPoll a fan-out batch: running while any task can still change, then completed, partial (some succeeded — normal for a best-effort batch) or failed, with per-task status and results. Each result carries the task_id you gave the task.
run_agent_loopRun the same task against an agent repeatedly (bounded, sequential), with templated messages and an optional stop signal. Poll with get_loop_status; stop gracefully with stop_loop. An agent-scoped key can loop only on itself or on agents it has permission to call — the same rule as chat_with_agent — and the refusal happens before any loop starts. get_loop_status and stop_loop apply the same rule to the loop's agent. See Agent Loops.
list_operator_queueRead the Operating Room queue (approvals, questions, alerts). Agent-scoped keys see only the calling agent plus its permitted agents. Complete within limit, with total, has_more, next_cursor and next_offset; page with cursor="start", then next_cursor. Resolve an item with respond_to_operator_queue.
ask_operatorRaise an approval, question or alert as the calling agent. An ask addressed to a role several people fill reaches each of them, and the first answer wins. Where your install provides roles, to may also name a canon role, role:<id>: it reaches only the people seated in it who can open the agent, with no fallback to the owner, and is refused with 422 role_unavailable, role_unassigned or role_cannot_open_agent instead. An ask to approver follows the same reach rule: it is refused with 422 role_cannot_open_agent when no seated approver can open the agent. Where your install provides projects, to: project reaches the project the current chat or room turn is on: its steward, else its creator, refused with 422 project_unavailable, not_in_project_turn or project_unreachable when it cannot reach either (see Approvals). It is checked at once and answered with a receipt; asking again with the same id returns the first receipt. Read how it ended with get_my_ask.
ask_for_credentialAsk the person you are chatting with for a secret by name (name, why). They type it into a masked field in their Workspace; it is stored in the agent's environment under that name and never appears in the chat, the ask or the agent's wake, which says only that it was provided. Use it only in a conversation with that person: with no single person to ask it is refused with 422 no_person, when neither the agent's primary contact nor its owner can open the agent in their Workspace with 422 role_cannot_open_agent, and a reserved or malformed name with 422 invalid_credential_name.
set_reminderSchedule a durable one-shot deferred self-trigger — the agent re-invokes itself later with a message it picks. Survives restarts; list with list_reminders, cancel with cancel_reminder. See Agent Reminders.
register_skill_sourceAdd a skills repository to the library from an MCP client, or re-apply it: an already-registered repository is updated in place (ref, priority, …) instead of duplicated. Follow with sync_skill_source; the sync tools say whether the sync ran, was refused_busy (another sync is running — retry) or failed, and point at get_skills_library_status → last_fleet_reinject when it started a fleet re-inject. Admin only — use an admin's own user-scoped key; agent keys never see it. The URL must not contain a token; private repositories use the instance's GitHub PAT.
run_skillRun a named skill headlessly (enterprise-gated; returns "disabled" in community builds). Discover runnable skills with list_runnable_skills.
create_roomOpen a shared multi-agent room and post/read messages (post_to_room / read_room / list_rooms / close_room). Rooms are bounded by message, cost, and time budgets — Rooms owns the budget defaults. Against an older backend that does not serve rooms the tools return a shared_sessions_not_enabled result.
set_canvasRender the agent's canvas in the Workspace — a block layout the person the agent works with sees beside the conversation. patch_canvas updates blocks in place; get_canvas / list_canvases read it back; clear_canvas empties it. See Agent Canvas.
fetch_credentialFetch a vault credential the agent has been granted, by name; list_available_credentials lists the granted names (never values). The value arrives live and is scrubbed from the saved transcript. Where the vault is not available the tools degrade to a result that says so rather than failing. See Credential Management.
call_userPlace an outbound phone call to a user and hold a voice conversation. Server-gated: works only when VoIP is enabled platform-wide and the agent has a voice binding; rate-limited and daily-capped. See VoIP Telephony.
share_fileThe agent drops a file into /home/developer/public/ and calls this tool to mint a signed, expiring download URL (universal — works for web, Slack, Telegram, WhatsApp, email).
write_user_memoryPer-user memory blob in an isolated store. Trinity resolves the user's email from execution_id server-side, so an agent cannot accidentally cross-write another user's memory.
send_messageProactive message to a person, addressed by role (to: primary, approver, viewer); the platform resolves who fills it. When nobody holds the primary seat, the agent's owner receives it; any other unfilled role, or one several people fill, is refused by name. recipient_email is deprecated. channel picks the delivery path: auto (default — Telegram, then Slack, then web), telegram, slack or web; web lands in the person's Workspace conversation with the agent, which reaches people who use only the Workspace but sends no notification. Rate-limited and audit-logged. Takes an optional idempotency_key (see Sending once across runs).
send_group_messageProactive message to a channel group (Slack channel, Telegram chat). Discovered via list_channel_groups. Takes an optional idempotency_key.
ask_trinityGrounded Q&A about Trinity itself, answered from the documentation. Pass the session_id it returns to ask follow-ups; the tool tells you when a session reset dropped your context. Also available standalone as the trinity-docs-mcp npx package, with no Trinity instance or API key required.
record_metricsRecord observations of the agent's declared business metrics as data. A batch is all-or-nothing, with a reason code per bad point; declare a metric in template.yaml first and call refresh_metric_definitions. Read back with get_metrics, and targets vs actuals with get_objectives. See Dynamic Dashboards.
get_agent_permissionsRead the agents an agent may call. Strict: when Docker can't be read you get an error, not an empty list. Only edges you can see are listed (observed_within), so a missing edge is not proof it was removed. get_agent_capability_grants reads the agent's five self-change permissions. An agent key reads only its own grants or those of agents it spawned, and any other target is refused. A refusal is an error, never "no grants".
reportPublish a structured report (table, KPI set, markdown, timeline); to addresses it to a role's person. Read them back with list_reports / get_report. See Agent Reports.

API Key Management

EndpointMethodDescription
/api/mcp/keysPOSTCreate API key (signed-in browser session only)
/api/mcp/keysGETList API keys (signed-in browser session only; an API key cannot list keys)
/api/mcp/keys/{key_id}GETOne key's metadata (never the secret)
/api/mcp/keys/{key_id}/revokePOSTDeactivate a key; its record stays for audit
/api/mcp/keys/{key_id}DELETEPermanently delete a key
/api/settings/mcp-urlGET/PUT/DELETEThe advertised MCP URL: read the override (url, null when none) and the auto-detected value (default_url), set an override, or clear it (admin)
/api/settings/mcp-external-accessGETExternal MCP access: enabled, source (settings, environment or default), env_value, the advertised_url and raw_port_bind_address (any signed-in user)
/api/settings/mcp-external-accessPUTTurn it on or off ({"enabled": true}; admin, recorded in the audit log)
/api/settings/mcp-external-accessDELETEClear the saved value so MCP_EXTERNAL_ACCESS or the default decides (admin)

MCP Endpoint

EndpointTransportDescription
http://localhost:8080/mcpStreamable HTTPMCP tool server on its own port (published on 127.0.0.1 on a fresh install)
https://your-domain.com/mcpStreamable HTTPThe same server, proxied by the production frontend — the URL for an install that exposes only 80/443

Both answer outside clients only while External MCP access is on.

Nevermined x402 Payments

Monetize agents with per-request payments using the Nevermined x402 payment protocol. Users pay per chat message; agents earn credits.

Setup

1

Open the agent detail page and navigate to payment settings.

2

Enter the NVM API Key, Agent ID, and Plan ID from Nevermined.

3

Enable payments. The agent now has a paid chat endpoint: POST /api/paid/{agent_name}/chat.

Payment Flow

Client -> POST /api/paid/{agent}/chat (no token)
  <- 402 Payment Required (includes payment info)

Client -> Purchases credits via Nevermined checkout page
Client -> POST /api/paid/{agent}/chat (payment-signature header)
  <- 200 OK (agent response, 1 credit deducted)

Payment API

EndpointMethodDescription
/api/paid/{agent_name}/chatPOSTPaid chat (returns 402/403/200)
/api/paid/{agent_name}/infoGETPayment requirements (no auth)
/api/nevermined/agents/{name}/configPOST/GET/DELETEConfigure payment settings
/api/nevermined/agents/{name}/config/togglePUTEnable or disable payments

Limitations

•Agent-scoped keys cannot access tools outside their assigned agent (plus explicitly permitted agents).
•MCP clients must be manually reconnected after a backend restart.
•A client connected with an API key keeps its MCP session when the MCP server itself restarts or is redeployed: its next call picks the session up again, provided the key is still active and the session is less than 30 days old. Each revival is written to the audit log. This does not cover a keyless email-code session (log in again), a call that was in flight at the moment of the restart, or the legacy /sse transport; a revived session sees an agent's dedicated chat_with_<agent> tools again within about 20 seconds. The session ids are signed with INTERNAL_API_SECRET, so changing that secret costs every connected client one reconnect.
•Outside clients are refused with external_mcp_access_off until an admin turns on External MCP access; a fresh install starts with it off.
•chat_with_agent and fan_out sync modes cap at MCP_CHAT_TIMEOUT_MS (default 25s). Longer calls switch to poll-mode via the returned execution_id (or fan_out_id); a receipt is issued only when the running work can be attributed to your call unambiguously.
•A model passed to chat_with_agent (it applies with parallel=true) must look like a model id — a short alias such as sonnet or a full id such as claude-sonnet-4-6. Anything else is refused with 422 before the task starts. See Chat API.
•Fan-out is self-only: an agent fans out to itself, not to another agent.
•chat_with_agent, fan_out stop at the agent-to-agent chain-depth limit (default 8 hops) and return a result marked retryable: false. See Agent Network.
•Only one Nevermined plan per agent. Settlement failures must be retried manually.

See Also

•Fan-Out — parallel dispatch and polling a batch
•Agent Network — agent-to-agent calls, async delegation and the timeout receipt
•Chat API — the REST routes the chat and task tools call
•A2A Protocol — A2A 0.3.0 discovery and inbound tasking for external orchestrators