From d557585b6d734a489ba08fd76bb3993d9ec799ba Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 2 Apr 2025 12:27:46 +0000 Subject: [PATCH 1/4] docs: clarify details around MCP --- docs/manifest.json | 113 ++++++++++++++++---- docs/tutorials/ai-agents/create-template.md | 4 +- docs/tutorials/ai-agents/custom-agents.md | 42 ++++++++ docs/tutorials/ai-agents/headless.md | 6 +- 4 files changed, 138 insertions(+), 27 deletions(-) create mode 100644 docs/tutorials/ai-agents/custom-agents.md diff --git a/docs/manifest.json b/docs/manifest.json index 0bb494317cf32..c9b0e1ebff629 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1,5 +1,7 @@ { - "versions": ["main"], + "versions": [ + "main" + ], "routes": [ { "title": "About", @@ -186,7 +188,9 @@ "description": "Use Coder Desktop to access your workspace like it's a local machine", "path": "./user-guides/desktop/index.md", "icon_path": "./images/icons/computer-code.svg", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Workspace Management", @@ -236,7 +240,10 @@ "title": "Appearance", "description": "Learn how to configure the appearance of Coder", "path": "./admin/setup/appearance.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Telemetry", @@ -317,22 +324,33 @@ { "title": "Groups \u0026 Roles", "path": "./admin/users/groups-roles.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "IdP Sync", "path": "./admin/users/idp-sync.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Organizations", "path": "./admin/users/organizations.md", - "state": ["premium"] + "state": [ + "premium" + ] }, { "title": "Quotas", "path": "./admin/users/quotas.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Sessions \u0026 API Tokens", @@ -474,7 +492,10 @@ "title": "Process Logging", "description": "Log workspace processes", "path": "./admin/templates/extending-templates/process-logging.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] } ] }, @@ -487,7 +508,10 @@ "title": "Permissions \u0026 Policies", "description": "Learn how to create templates with Terraform", "path": "./admin/templates/template-permissions.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Troubleshooting Templates", @@ -501,13 +525,19 @@ "description": "Learn how to run external provisioners with Coder", "path": "./admin/provisioners/index.md", "icon_path": "./images/icons/key.svg", - "state": ["enterprise", "premium"], + "state": [ + "enterprise", + "premium" + ], "children": [ { "title": "Manage Provisioner Jobs", "description": "Learn how to run external provisioners with Coder", "path": "./admin/provisioners/manage-provisioner-jobs.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] } ] }, @@ -585,13 +615,19 @@ "title": "Workspace Proxies", "description": "Run geo distributed workspace proxies", "path": "./admin/networking/workspace-proxies.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "High Availability", "description": "Learn how to configure Coder for High Availability", "path": "./admin/networking/high-availability.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Troubleshooting", @@ -650,7 +686,10 @@ "title": "Audit Logs", "description": "Audit actions taken inside Coder", "path": "./admin/security/audit-logs.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] }, { "title": "Secrets", @@ -661,7 +700,10 @@ "title": "Database Encryption", "description": "Encrypt the database to prevent unauthorized access", "path": "./admin/security/database-encryption.md", - "state": ["enterprise", "premium"] + "state": [ + "enterprise", + "premium" + ] } ] }, @@ -720,7 +762,9 @@ "title": "Run AI Coding Agents with Coder", "description": "Learn how to run and secure agents in Coder", "path": "./tutorials/ai-agents/README.md", - "state": ["early access"], + "state": [ + "early access" + ], "children": [ { "title": "Learn about coding agents", @@ -731,42 +775,65 @@ "title": "Create a Coder template for agents", "description": "Create a purpose-built template for your AI agents", "path": "./tutorials/ai-agents/create-template.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Integrate with your issue tracker", "description": "Assign tickets to AI agents and interact via code reviews", "path": "./tutorials/ai-agents/issue-tracker.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Best practices \u0026 adding tools via MCP", "description": "Improve results by adding tools to your agents", "path": "./tutorials/ai-agents/best-practices.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Supervise agents via Coder UI", "description": "Interact with agents via the Coder UI", "path": "./tutorials/ai-agents/coder-dashboard.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Supervise agents via the IDE", "description": "Interact with agents via VS Code or Cursor", "path": "./tutorials/ai-agents/ide-integration.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "title": "Programmatically manage agents", "description": "Manage agents via MCP, the Coder CLI, and/or REST API", "path": "./tutorials/ai-agents/headless.md", - "state": ["early access"] + "state": [ + "early access" + ] }, { "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 index 6a203593575eb..26fc0545b63a0 100644 --- a/docs/tutorials/ai-agents/create-template.md +++ b/docs/tutorials/ai-agents/create-template.md @@ -41,8 +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, +> Alternatively, you can [report status from a custom agent]() back to the Coder +> control plane via MCP (`coder exp mcp server`). For more information, > [join our Discord](https://discord.gg/coder) or > [contact us](https://coder.com/contact). diff --git a/docs/tutorials/ai-agents/custom-agents.md b/docs/tutorials/ai-agents/custom-agents.md new file mode 100644 index 0000000000000..67bc2de248dd4 --- /dev/null +++ b/docs/tutorials/ai-agents/custom-agents.md @@ -0,0 +1,42 @@ +# 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. diff --git a/docs/tutorials/ai-agents/headless.md b/docs/tutorials/ai-agents/headless.md index e7fdb03e33633..60f203eaef2f4 100644 --- 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 [configuring templates](./create-template.md). + ## Coder CLI Workspaces can be created, started, and stopped via the Coder CLI. See the From 70305c21af75834bac18d16cb9c8512f02b93acc Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 2 Apr 2025 12:35:21 +0000 Subject: [PATCH 2/4] fix --- docs/tutorials/ai-agents/create-template.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/ai-agents/create-template.md b/docs/tutorials/ai-agents/create-template.md index 26fc0545b63a0..4f7501371e841 100644 --- 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 MCP (`coder exp 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 From ac9c11693202d531172b2beceed4a76a9a11f164 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Wed, 2 Apr 2025 12:37:44 +0000 Subject: [PATCH 3/4] contributing --- docs/tutorials/ai-agents/custom-agents.md | 6 ++++++ docs/tutorials/ai-agents/headless.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/ai-agents/custom-agents.md b/docs/tutorials/ai-agents/custom-agents.md index 67bc2de248dd4..e1a83ae1ead75 100644 --- a/docs/tutorials/ai-agents/custom-agents.md +++ b/docs/tutorials/ai-agents/custom-agents.md @@ -40,3 +40,9 @@ 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 index 60f203eaef2f4..acf95712fb468 100644 --- a/docs/tutorials/ai-agents/headless.md +++ b/docs/tutorials/ai-agents/headless.md @@ -39,7 +39,7 @@ coder exp mcp configure claude-desktop # Configure Claude Desktop to interact wi 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 [configuring templates](./create-template.md). +> 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 From 02b750ab177ca8daf71a2acbc2e10dc85a935c22 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 2 Apr 2025 13:43:34 +0100 Subject: [PATCH 4/4] fmt --- docs/manifest.json | 108 ++++++++++----------------------------------- 1 file changed, 24 insertions(+), 84 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index c9b0e1ebff629..c0845490606b8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1,7 +1,5 @@ { - "versions": [ - "main" - ], + "versions": ["main"], "routes": [ { "title": "About", @@ -188,9 +186,7 @@ "description": "Use Coder Desktop to access your workspace like it's a local machine", "path": "./user-guides/desktop/index.md", "icon_path": "./images/icons/computer-code.svg", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Workspace Management", @@ -240,10 +236,7 @@ "title": "Appearance", "description": "Learn how to configure the appearance of Coder", "path": "./admin/setup/appearance.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Telemetry", @@ -324,33 +317,22 @@ { "title": "Groups \u0026 Roles", "path": "./admin/users/groups-roles.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "IdP Sync", "path": "./admin/users/idp-sync.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Organizations", "path": "./admin/users/organizations.md", - "state": [ - "premium" - ] + "state": ["premium"] }, { "title": "Quotas", "path": "./admin/users/quotas.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Sessions \u0026 API Tokens", @@ -492,10 +474,7 @@ "title": "Process Logging", "description": "Log workspace processes", "path": "./admin/templates/extending-templates/process-logging.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] } ] }, @@ -508,10 +487,7 @@ "title": "Permissions \u0026 Policies", "description": "Learn how to create templates with Terraform", "path": "./admin/templates/template-permissions.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Troubleshooting Templates", @@ -525,19 +501,13 @@ "description": "Learn how to run external provisioners with Coder", "path": "./admin/provisioners/index.md", "icon_path": "./images/icons/key.svg", - "state": [ - "enterprise", - "premium" - ], + "state": ["enterprise", "premium"], "children": [ { "title": "Manage Provisioner Jobs", "description": "Learn how to run external provisioners with Coder", "path": "./admin/provisioners/manage-provisioner-jobs.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] } ] }, @@ -615,19 +585,13 @@ "title": "Workspace Proxies", "description": "Run geo distributed workspace proxies", "path": "./admin/networking/workspace-proxies.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "High Availability", "description": "Learn how to configure Coder for High Availability", "path": "./admin/networking/high-availability.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Troubleshooting", @@ -686,10 +650,7 @@ "title": "Audit Logs", "description": "Audit actions taken inside Coder", "path": "./admin/security/audit-logs.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] }, { "title": "Secrets", @@ -700,10 +661,7 @@ "title": "Database Encryption", "description": "Encrypt the database to prevent unauthorized access", "path": "./admin/security/database-encryption.md", - "state": [ - "enterprise", - "premium" - ] + "state": ["enterprise", "premium"] } ] }, @@ -762,9 +720,7 @@ "title": "Run AI Coding Agents with Coder", "description": "Learn how to run and secure agents in Coder", "path": "./tutorials/ai-agents/README.md", - "state": [ - "early access" - ], + "state": ["early access"], "children": [ { "title": "Learn about coding agents", @@ -775,65 +731,49 @@ "title": "Create a Coder template for agents", "description": "Create a purpose-built template for your AI agents", "path": "./tutorials/ai-agents/create-template.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Integrate with your issue tracker", "description": "Assign tickets to AI agents and interact via code reviews", "path": "./tutorials/ai-agents/issue-tracker.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Best practices \u0026 adding tools via MCP", "description": "Improve results by adding tools to your agents", "path": "./tutorials/ai-agents/best-practices.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Supervise agents via Coder UI", "description": "Interact with agents via the Coder UI", "path": "./tutorials/ai-agents/coder-dashboard.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Supervise agents via the IDE", "description": "Interact with agents via VS Code or Cursor", "path": "./tutorials/ai-agents/ide-integration.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Programmatically manage agents", "description": "Manage agents via MCP, the Coder CLI, and/or REST API", "path": "./tutorials/ai-agents/headless.md", - "state": [ - "early access" - ] + "state": ["early access"] }, { "title": "Securing agents in Coder", "description": "Learn how to secure agents with boundaries", "path": "./tutorials/ai-agents/securing.md", - "state": [ - "early access" - ] + "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" - ] + "state": ["early access"] } ] },