agent mcp tools docs

ericallam · ericallam · commit 54aca86869b3 · 2026-04-02T16:13:19.000+01:00
diff --git a/docs/ai-chat/mcp.mdx b/docs/ai-chat/mcp.mdx
@@ -0,0 +1,97 @@
+---
+title: "MCP Server"
+sidebarTitle: "MCP Server"
+description: "Chat with your agents from any AI coding tool using the Trigger.dev MCP server."
+---
+
+The Trigger.dev MCP server includes tools for having conversations with your chat agents directly from AI coding tools like Claude Code, Cursor, Windsurf, and others. This lets your AI assistant interact with your agents without writing any code.
+
+## Available tools
+
+| Tool | Description |
+| --- | --- |
+| `list_agents` | List all agents in the current worker |
+| `start_agent_chat` | Start a conversation with an agent |
+| `send_agent_message` | Send a message and get the response |
+| `close_agent_chat` | Close a conversation |
+
+See the [MCP Tools Reference](/mcp-tools#agent-chat-tools) for full details on each tool.
+
+## Typical workflow
+
+<Steps>
+  <Step title="List available agents">
+    Ask your AI assistant to list agents in your project. This calls `list_agents` which returns all tasks created with `chat.agent()` or `chat.customAgent()`.
+  </Step>
+  <Step title="Start a chat">
+    Start a conversation with an agent using `start_agent_chat`. This triggers a run and optionally preloads the agent so it's ready to respond immediately.
+
+    If the agent uses `withClientData`, pass the required fields via `clientData`.
+  </Step>
+  <Step title="Send messages">
+    Send messages with `send_agent_message`. The agent processes each message and returns the full response text, including which tools were used. The agent retains full context across messages in the same chat.
+  </Step>
+  <Step title="Close the chat">
+    When done, close the conversation with `close_agent_chat`. This signals the agent to exit gracefully. If you skip this step, the agent will close on its own when its idle timeout expires.
+  </Step>
+</Steps>
+
+## Example conversation
+
+Here's what a typical MCP conversation with an agent looks like:
+
+```
+You: List my agents
+
+AI: Found 3 agents in worker 20250402.12 (dev):
+    - support-agent (src/trigger/support.ts)
+    - pr-review (src/trigger/pr-review.ts)
+    - research (src/trigger/research.ts)
+
+You: Start a chat with the support agent
+
+AI: Agent chat started and preloaded.
+    - Chat ID: abc-123
+    - Agent: support-agent
+    - Run ID: run_xyz
+
+You: Ask it to look up order #4821
+
+AI: I found order #4821. It was placed on March 15 and shipped via
+    FedEx (tracking: 7891234). Current status: In Transit, estimated
+    delivery March 19.
+
+    Tools used: lookupOrder, getShippingStatus
+
+You: Close the chat
+
+AI: Chat abc-123 closed.
+```
+
+## Setup
+
+If you haven't set up the MCP server yet, see the [MCP Server introduction](/mcp-introduction) for installation and client configuration.
+
+Agent chat tools require:
+- A running dev server (`trigger dev`) or a deployed worker
+- At least one agent defined with `chat.agent()` or `chat.customAgent()`
+
+## How it works
+
+Under the hood, the MCP tools use the same protocol as the [frontend transport](/ai-chat/frontend) and [AgentChat SDK](/ai-chat/server-chat):
+
+1. **`start_agent_chat`** triggers a task run with the `preload` trigger and stores the session (run ID, chat ID) in memory.
+2. **`send_agent_message`** sends the message via the run's input stream and subscribes to the output SSE stream to collect the agent's full response.
+3. **`close_agent_chat`** sends a close signal via the input stream and removes the session.
+
+Sessions are held in-memory within the MCP server process. If the MCP server restarts, active sessions are lost — but the underlying agent runs continue until their idle timeout.
+
+<Note>
+  The `get_current_worker` tool also labels agents with `[agent]` in its output, making it easy to identify which tasks are agents even when listing all tasks.
+</Note>
+
+## See also
+
+- [AgentChat SDK](/ai-chat/server-chat) — programmatic server-side access to agents
+- [Sub-Agents](/ai-chat/patterns/sub-agents) — agents calling other agents
+- [MCP Tools Reference](/mcp-tools#agent-chat-tools) — full tool parameter reference
diff --git a/docs/ai-chat/patterns/sub-agents.mdx b/docs/ai-chat/patterns/sub-agents.mdx
diff --git a/docs/ai-chat/server-chat.mdx b/docs/ai-chat/server-chat.mdx
@@ -175,7 +175,7 @@ const researchTool = tool({
 
 This supports single-turn delegation, multi-turn LLM-driven conversations with persistent sub-agents, and cross-turn state that survives snapshot/restore.
 
-See the [Sub-Agents guide](/ai-chat/sub-agents) for the full pattern including multi-turn conversations, cleanup, and what the frontend sees.
+See the [Sub-Agents guide](/ai-chat/patterns/sub-agents) for the full pattern including multi-turn conversations, cleanup, and what the frontend sees.
 
 ## Additional methods
 
diff --git a/docs/docs.json b/docs/docs.json
@@ -92,15 +92,16 @@
                   "ai-chat/backend",
                   "ai-chat/frontend",
                   "ai-chat/server-chat",
-                  "ai-chat/sub-agents",
                   "ai-chat/types",
                   "ai-chat/features",
                   "ai-chat/compaction",
                   "ai-chat/pending-messages",
                   "ai-chat/background-injection",
+                  "ai-chat/mcp",
                   {
                     "group": "Patterns",
                     "pages": [
+                      "ai-chat/patterns/sub-agents",
                       "ai-chat/patterns/database-persistence",
                       "ai-chat/patterns/code-sandbox"
                     ]
diff --git a/docs/mcp-tools.mdx b/docs/mcp-tools.mdx
@@ -131,3 +131,56 @@ List all preview branches in the project.
 <Callout type="warning">
   The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag.
 </Callout>
+
+## Agent Chat Tools
+
+These tools let you have conversations with [chat agents](/ai-chat/overview) directly from your AI coding tool. See the [Agent MCP guide](/ai-chat/mcp) for a walkthrough.
+
+### list_agents
+
+List all chat agents registered in the current worker. Agents are tasks created with `chat.agent()` or `chat.customAgent()`.
+
+**Example usage:**
+- `"What agents are available?"`
+- `"List my chat agents"`
+
+### start_agent_chat
+
+Start a conversation with a chat agent. Returns a chat ID for use with `send_agent_message`. Optionally preloads the agent so it initializes before the first message.
+
+**Parameters:**
+- `agentId` (required) — The agent task slug (e.g., `"support-agent"`)
+- `chatId` (optional) — A custom conversation ID. Auto-generated if omitted
+- `clientData` (optional) — Client data to include with every message (e.g., `{ userId: "user_123" }`). Must match the agent's `clientDataSchema` if one is defined
+- `preload` (optional, default: `true`) — Whether to preload the agent before the first message
+
+**Example usage:**
+- `"Start a chat with the support agent"`
+- `"Talk to the pr-review agent with userId abc"`
+
+### send_agent_message
+
+Send a message to an active agent chat and get the full response back. The agent remembers full context from previous messages in the same chat.
+
+**Parameters:**
+- `chatId` (required) — The chat ID from `start_agent_chat`
+- `message` (required) — The message text to send
+
+**Example usage:**
+- `"Tell the agent to review the latest PR"`
+- `"Ask it what tools it has available"`
+
+### close_agent_chat
+
+Close an agent chat conversation. The agent exits its loop gracefully. Without this, the agent will close on its own when its idle timeout expires.
+
+**Parameters:**
+- `chatId` (required) — The chat ID to close
+
+**Example usage:**
+- `"Close the chat"`
+- `"End the conversation"`
+
+<Callout type="warning">
+  The `start_agent_chat`, `send_agent_message`, and `close_agent_chat` tools are write operations and are not available in readonly mode.
+</Callout>
