docs: clarify details around MCP (#17220)

bpmct · web-flow · commit 13997cacb12d · 2025-04-02T12:48:08.000Z
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -766,7 +766,14 @@
 						{
 							"title": "Securing agents in Coder",
 							"description": "Learn how to secure agents with boundaries",
-							"path": "./tutorials/ai-agents/securing.md"
+							"path": "./tutorials/ai-agents/securing.md",
+							"state": ["early access"]
+						},
+						{
+							"title": "Custom agents",
+							"description": "Learn how to use custom agents with Coder",
+							"path": "./tutorials/ai-agents/custom-agents.md",
+							"state": ["early access"]
 						}
 					]
 				},
diff --git a/docs/tutorials/ai-agents/create-template.md b/docs/tutorials/ai-agents/create-template.md
@@ -41,10 +41,8 @@ Follow the instructions in the Coder Registry to install the module. Be sure to
 enable the `experiment_use_screen` and `experiment_report_tasks` variables to
 report status back to the Coder control plane.
 
-> Alternatively, you can report status from a custom agent back to the Coder
-> control plane via our MCP server. For more information,
-> [join our Discord](https://discord.gg/coder) or
-> [contact us](https://coder.com/contact).
+> Alternatively, you can [use a custom agent](./custom-agents.md) that is
+> not in our registry via MCP.
 
 ## 3. Confirm tasks are streaming in the Coder UI
 
diff --git a/docs/tutorials/ai-agents/custom-agents.md b/docs/tutorials/ai-agents/custom-agents.md
@@ -0,0 +1,48 @@
+# Custom Agents
+
+> [!NOTE]
+>
+> This functionality is in early access and subject to change. Do not run in
+> production as it is unstable. Instead, deploy these changes into a demo or
+> staging environment.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder.
+
+## Prerequisites
+
+- A Coder deployment with v2.21 or later
+- A [Coder workspace / template](./create-template.md)
+- A custom agent that supports Model Context Protocol (MCP)
+
+## Getting Started
+
+Coder uses the [MCP protocol](https://modelcontextprotocol.io/introduction) to report activity back to the Coder control plane. From there, activity is displayed in the Coder dashboard.
+
+First, your template will need a [coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) for the agent. This can be a web app or command run in the terminal and ideally gives the user a UI to interact with or view more details about the agent.
+
+From there, the agent can run the MCP server with the `coder exp mcp server` command. You will need to set the `CODER_MCP_APP_STATUS_SLUG` environment variable to match the slug in the coder_app resource.
+
+## Example
+
+Inside a Coder workspace, run the following commands:
+
+```sh
+coder login # be sure to be authenticated with the Coder CLI
+export CODER_MCP_APP_STATUS_SLUG=my-agent # needs to be the same as the slug in the coder_app resource
+
+# Use your own agent's logic and syntax here:
+any-custom-agent configure-mcp --name "coder" --command "coder exp mcp server"
+```
+
+This will start the MCP server and report activity back to the Coder control plane on behalf of the coder_app resource.
+
+> See the [Goose module](https://github.com/coder/modules/blob/main/goose/main.tf) source code for a real world example.
+
+## Contributing
+
+We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)!
+
+See our [contributing guide](https://github.com/coder/modules/blob/main/CONTRIBUTING.md) for more information.
diff --git a/docs/tutorials/ai-agents/headless.md b/docs/tutorials/ai-agents/headless.md
@@ -35,10 +35,12 @@ The Coder CLI has options to automatically configure MCP servers for you. On
 your local machine, run the following command:
 
 ```sh
-coder mcp claude-desktop # Configure Claude Desktop to interact with Coder
-coder mcp cursor # Configure Cursor to interact with Coder
+coder exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder
+coder exp mcp configure cursor # Configure Cursor to interact with Coder
 ```
 
+> MCP is also used for various agents to report activity back to Coder. Learn more about this in [custom agents](./custom-agents.md).
+
 ## Coder CLI
 
 Workspaces can be created, started, and stopped via the Coder CLI. See the

Original file line number	Diff line number	Diff line change
`@@ -766,7 +766,14 @@`
`766`	`766`	`{`
`767`	`767`	`"title": "Securing agents in Coder",`
`768`	`768`	`"description": "Learn how to secure agents with boundaries",`
`769`		`- "path": "./tutorials/ai-agents/securing.md"`
	`769`	`+ "path": "./tutorials/ai-agents/securing.md",`
	`770`	`+ "state": ["early access"]`
	`771`	`+ },`
	`772`	`+ {`
	`773`	`+ "title": "Custom agents",`
	`774`	`+ "description": "Learn how to use custom agents with Coder",`
	`775`	`+ "path": "./tutorials/ai-agents/custom-agents.md",`
	`776`	`+ "state": ["early access"]`
`770`	`777`	`}`
`771`	`778`	`]`
`772`	`779`	`},`