Guides/MCP Integration

MCP Integration

Trinity's MCP server exposes 74 tools for agent orchestration via the Model Context Protocol, enabling programmatic control from Claude Code, other MCP clients, or agent-to-agent communication.

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 and can be scoped to specific agents.

Authentication

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

Go to the API Keys page (/api-keys).

Click Create Key. Optionally scope the key to a specific agent.

Copy the generated key (prefixed trinity_mcp_*).

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

Connecting from Claude Code

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

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

Tool Categories

The MCP server organizes 74 tools across these modules:

Module	Tools	Description
agents.ts	19	Agent lifecycle, credentials, SSH, local deploy, GitHub sync, per-agent PAT
chat.ts	3	Chat (gateway-timeout safe), history, logs
schedules.ts	8	Schedule CRUD and execution history
executions.ts	3	Execution queries, async polling, activity monitoring
skills.ts	7	Skill management and assignment
tags.ts	5	Agent tagging
systems.ts	4	System manifest deployment
subscriptions.ts	6	Subscription management
monitoring.ts	3	Fleet health
nevermined.ts	4	Payment configuration
notifications.ts	1	Agent-to-platform notifications
events.ts	4	Agent event pub/sub
docs.ts	1	Agent documentation
channels.ts	2	Channel group discovery + proactive group messaging
messages.ts	1	Proactive user messaging by verified email
files.ts	1	`share_file` — publish file to a signed download URL
memory.ts	1	`write_user_memory` — per-user memory blob, isolated server-side

Key Tools Worth Knowing

Tool	Why it exists
chat_with_agent	Send a message to another agent. Gateway-timeout safe: if the sync call exceeds `MCP_CHAT_TIMEOUT_MS` (default 25s), it returns `{status: "queued_timeout", execution_id, message}` so the caller polls instead of duplicate-queueing the request.
share_file	The 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_memory	Per-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_message	Proactive message to a specific user by verified email. Rate-limited and audit-logged.
send_group_message	Proactive message to a channel group (Slack channel, Telegram chat). Discovered via `list_channel_groups`.

API Key Management

Endpoint	Method	Description
/api/mcp/keys	POST	Create API key
/api/mcp/keys	GET	List API keys
/api/mcp/keys/{key_id}	DELETE	Revoke API key

Nevermined x402 Payments

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

Setup

Open the agent detail page and navigate to payment settings.

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

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

Endpoint	Method	Description
/api/paid/{agent_name}/chat	POST	Paid chat (returns 402/403/200)
/api/paid/{agent_name}/info	GET	Payment requirements (no auth)
/api/nevermined/agents/{name}/config	POST/GET/DELETE	Configure payment settings
/api/nevermined/agents/{name}/config/toggle	PUT	Enable or disable payments

Limitations

•API keys are invalidated when the backend restarts.

•Agent-scoped keys cannot access tools outside their assigned agent.

•MCP clients must be manually reconnected after a backend restart.

•chat_with_agent sync mode caps at MCP_CHAT_TIMEOUT_MS (default 25s). Long-running calls beyond that switch to poll-mode via the returned execution_id.

•Only one Nevermined plan per agent. Settlement failures must be retried manually.

Subscription Credentials Scheduling