Jul 7, 2025 · Jun 30, 2025 · Jun 30, 2025 · Jun 30, 2025 · Jun 30, 2025 · Jul 2, 2025
diff --git a/docs/ai-coder/agents.md b/docs/ai-coder/agents.md
diff --git a/docs/ai-coder/best-practices.md b/docs/ai-coder/best-practices.md
 #Model Context Protocols (MCP) and adding AI tools
 #Best Practices

 >[!NOTE]
 >
 >This functionality is in beta and is evolving rapidly.
 >
 >When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
 >Always review AI-generated content before using it in critical systems.
 >
 >Join our[Discord channel](https://discord.gg/coder) or
 >[contact us](https://coder.com/contact) to get help or share feedback.
 This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization.

 ##Overview
 ##Identify Use Cases

 Coder templates should be pre-equipped with the tools and dependencies needed
 for development. With AI Agents, this is no exception.
 To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case.

 ##Prerequisites
 Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case:

 - A Coder deployment with v2.21 or later
 - A[template configured for AI agents](./create-template.md)
 | Scenario| Description| Examples| Tools|
 |------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
 |**Automating actions in the IDE**| Supplement tedious development with agents| Small refactors, generating unit tests, writing inline documentation, code search and navigation|[IDE Agents](./ide-agents.md) in Workspaces|
 |**Developer-led investigation and setup**| Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work| Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations|[Tasks](./tasks.md), to a full IDE with[Workspaces](../user-guides/workspace-access/index.md)|
 |**Prototyping & Business Applications**| User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases| Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development|[Tasks](./tasks.md)|
 |**Full background jobs & long-running agents**| Agents that run independently without user interaction for extended periods of time| Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting|[Tasks](./tasks.md) API*(in development)*|
 |**External agents and chat clients**| External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing| ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis|[MCP Server](./mcp-server.md)|

 ##Best Practices
 ##Provide Agents with Proper Context

 - Use the most capable ML models you have access to in order to evaluate Agent
  performance.
 - Set a system prompt with the`AI_SYSTEM_PROMPT` environment in your template
 - Within your repositories, write a`.cursorrules`,`CLAUDE.md` or similar file
  to guide the agent's behavior.
 - To read issue descriptions or pull request comments, install the proper CLI
  (e.g.`gh`) in your image/template.
 - Ensure your[template](./create-template.md) is truly pre-configured for
  development without manual intervention (e.g. repos are cloned, dependencies
  are built, secrets are added/mocked, etc.).
 While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization.

 >Note:[External authentication](../admin/external-auth/index.md) can be helpful
 >to authenticate with third-party services such as GitHub or JFrog.
 ###Memory

 - Give your agent the proper tools via MCP to interact with your codebase and
  related services.
 - Read our recommendations on[securing agents](./securing.md) to avoid
  surprises.
 Coding Agents like Claude Code often refer to a[memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization.

 ##Adding Tools via MCP
 Look up the docs for the specific agent you're using to learn more about how to provide context to your agents.

 Model Context Protocol (MCP) is an emerging standard for adding tools to your
 agents.
 ###Tools (Model Context Protocol)

 Follow the documentation for your[agent](./agents.md) to learn how to configure
 MCP servers. See
 [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
 to browse open source MCP servers.
 Agents can also use tools, often via[Model Context Protocol](https://modelcontextprotocol.io/introduction) to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog.

 ###Our Favorite MCP Servers
 Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents.

 In internal testing, we have seen significant improvements in agent performance
 when these tools are added via MCP.
 ####Our Favorite MCP Servers

 In internal testing, we have seen significant improvements in agent performance when these tools are added via MCP.

 -[Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
  to open a browser, and check its work by viewing output and taking
  screenshots.
 -[desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP):
  Instruct your agent to run long-running tasks (e.g.`npm run dev`) in the
  background instead of blocking the main thread.
  Instruct your agent to run long-running tasks (e.g.`npm run dev`) in the background instead of blocking the main thread.

 ##Security & Permissions

 LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously.

 [Learn more about securing agents with Coder Tasks](./security.md)

 ##Next Steps
 ##Keep it Simple

 -[Supervise Agents in the UI](./coder-dashboard.md)
 -[Supervise Agents in the IDE](./ide-integration.md)
 -[Supervise Agents Programmatically](./headless.md)
 -[Securing Agents](./securing.md)
 Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time.
diff --git a/docs/ai-coder/coder-dashboard.md b/docs/ai-coder/coder-dashboard.md
diff --git a/docs/ai-coder/create-template.md b/docs/ai-coder/create-template.md
diff --git a/docs/ai-coder/custom-agents.md b/docs/ai-coder/custom-agents.md
 # Custom Agents

 > [!NOTE]
 >
 > This functionality is in beta and is evolving rapidly.
 >
 > When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
 > Always review AI-generated content before using it in critical systems.
 >
 > 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.
 Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks.

 ## Prerequisites

 - A Coder deployment with v2.21 or later
 - A [Coder workspace / template](./create-template.md)
 - A [Coder workspace / template](../admin/templates/creating-templates.md)
 - A custom agent that supports Model Context Protocol (MCP)

 ## Getting Started
 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
 coder login
 export CODER_MCP_APP_STATUS_SLUG=my-agent

 # 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/registry/blob/main/registry/coder/modules/goose/main.tf) source code for a real world example.
 > [!NOTE]
 > See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/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/registry/blob/main/CONTRIBUTING.md) for more information.
 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/registry/blob/main/CONTRIBUTING.md) for more information.
Original file line number	Diff line number	Diff line change
		@@ -1,71 +1,53 @@
		#Model Context Protocols (MCP) and adding AI tools
		#Best Practices

		>[!NOTE]
		>
		>This functionality is in beta and is evolving rapidly.
		>
		>When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
		>Always review AI-generated content before using it in critical systems.
		>
		>Join our[Discord channel](https://discord.gg/coder) or
		>[contact us](https://coder.com/contact) to get help or share feedback.
		This document includes a mix of cultural and technical best practices and guidelines for introducing AI agents into your organization.

		##Overview
		##Identify Use Cases

		Coder templates should be pre-equipped with the tools and dependencies needed
		for development. With AI Agents, this is no exception.
		To successfully implement AI coding agents, identify 3-5 practical use cases where AI tools can deliver real value. Additionally, find a target group of developers and projects that are the best candidates for each specific use case.

		##Prerequisites
		Below are common scenarios where AI coding agents provide the most impact, along with the right tools for each use case:

		- A Coder deployment with v2.21 or later
		- A[template configured for AI agents](./create-template.md)
		\| Scenario\| Description\| Examples\| Tools\|
		\|------------------------------------------------\|---------------------------------------------------------------------------------------------------------------------------\|----------------------------------------------------------------------------------------------------------------------\|------------------------------------------------------------------------------------------------\|
		\|Automating actions in the IDE\| Supplement tedious development with agents\| Small refactors, generating unit tests, writing inline documentation, code search and navigation\|[IDE Agents](./ide-agents.md) in Workspaces\|
		\|Developer-led investigation and setup\| Developers delegate research and initial implementation to AI, then take over in their preferred IDE to complete the work\| Bug triage and analysis, exploring technical approaches, understanding legacy code, creating starter implementations\|[Tasks](./tasks.md), to a full IDE with[Workspaces](../user-guides/workspace-access/index.md)\|
		\|Prototyping & Business Applications\| User-friendly interface for engineers and non-technical users to build and prototype within new or existing codebases\| Creating dashboards, building simple web apps, data analysis workflows, proof-of-concept development\|[Tasks](./tasks.md)\|
		\|Full background jobs & long-running agents\| Agents that run independently without user interaction for extended periods of time\| Automated code reviews, scheduled data processing, continuous integration tasks, monitoring and alerting\|[Tasks](./tasks.md) API(in development)\|
Copy link Collaborator stirbyJul 7, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I tell a lot of customers that background jobs should always have a clear outcome withtests. I think it's good to explain that long-running tasks should have well-defined final states.
		\|External agents and chat clients\| External AI agents and chat clients that need access to Coder workspaces for development environments and code sandboxing\| ChatGPT, Claude Desktop, custom enterprise agents running tests, performing development tasks, code analysis\|[MCP Server](./mcp-server.md)\|

		##Best Practices
		##Provide Agents with Proper Context

		- Use the most capable ML models you have access to in order to evaluate Agent
		performance.
		- Set a system prompt with the`AI_SYSTEM_PROMPT` environment in your template
		- Within your repositories, write a`.cursorrules`,`CLAUDE.md` or similar file
		to guide the agent's behavior.
		- To read issue descriptions or pull request comments, install the proper CLI
		(e.g.`gh`) in your image/template.
		- Ensure your[template](./create-template.md) is truly pre-configured for
		development without manual intervention (e.g. repos are cloned, dependencies
		are built, secrets are added/mocked, etc.).
		While LLMs are trained on general knowledge, it's important to provide additional context to help agents understand your codebase and organization.

		>Note:[External authentication](../admin/external-auth/index.md) can be helpful
		>to authenticate with third-party services such as GitHub or JFrog.
		###Memory

		- Give your agent the proper tools via MCP to interact with your codebase and
		related services.
		- Read our recommendations on[securing agents](./securing.md) to avoid
		surprises.
		Coding Agents like Claude Code often refer to a[memory file](https://docs.anthropic.com/en/docs/claude-code/memory) in order to gain context about your repository or organization.

		##Adding Tools via MCP
		Look up the docs for the specific agent you're using to learn more about how to provide context to your agents.

		Model Context Protocol (MCP) is an emerging standard for adding tools to your
		agents.
		###Tools (Model Context Protocol)

		Follow the documentation for your[agent](./agents.md) to learn how to configure
		MCP servers. See
		[modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
		to browse open source MCP servers.
		Agents can also use tools, often via[Model Context Protocol](https://modelcontextprotocol.io/introduction) to look up information or perform actions. A common example would be fetching style guidelines from an internal wiki, or looking up the documentation for a service within your catalog.

		###Our Favorite MCP Servers
		Look up the docs for the specific agent you're using to learn more about how to provide tools to your agents.

		In internal testing, we have seen significant improvements in agent performance
		when these tools are added via MCP.
		####Our Favorite MCP Servers

		In internal testing, we have seen significant improvements in agent performance when these tools are added via MCP.

		-[Playwright](https://github.com/microsoft/playwright-mcp): Instruct your agent
		to open a browser, and check its work by viewing output and taking
		screenshots.
		-[desktop-commander](https://github.com/wonderwhy-er/DesktopCommanderMCP):
		Instruct your agent to run long-running tasks (e.g.`npm run dev`) in the
		background instead of blocking the main thread.
		Instruct your agent to run long-running tasks (e.g.`npm run dev`) in the background instead of blocking the main thread.

		##Security & Permissions

		LLMs and agents can be dangerous if not run with proper boundaries. Be sure not to give agents full permissions on behalf of a user, and instead use separate identities with limited scope whenever interacting autonomously.

		[Learn more about securing agents with Coder Tasks](./security.md)

		##Next Steps
		##Keep it Simple

		-[Supervise Agents in the UI](./coder-dashboard.md)
		-[Supervise Agents in the IDE](./ide-integration.md)
		-[Supervise Agents Programmatically](./headless.md)
		-[Securing Agents](./securing.md)
		Today's LLMs and AI agents are not going to refactor entire codebases with production-grade code on their own! Using coding agents can be extremely fun and productive, but it is important to keep the scope of your use cases small and simple, and grow them over time.
Original file line number	Diff line number	Diff line change
		@@ -1,21 +1,11 @@
		# Custom Agents

		> [!NOTE]
		>
		> This functionality is in beta and is evolving rapidly.
		>
		> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
		> Always review AI-generated content before using it in critical systems.
		>
		> 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.
		Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks.

		## Prerequisites

		- A Coder deployment with v2.21 or later
		- A [Coder workspace / template](./create-template.md)
		- A [Coder workspace / template](../admin/templates/creating-templates.md)
		- A custom agent that supports Model Context Protocol (MCP)

		## Getting Started
Expand All		@@ -31,19 +21,18 @@ From there, the agent can run the MCP server with the `coder exp mcp server` com
		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
		coder login
		export CODER_MCP_APP_STATUS_SLUG=my-agent

		# 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/registry/blob/main/registry/coder/modules/goose/main.tf) source code for a real world example.
		> [!NOTE]
		> See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/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/registry/blob/main/CONTRIBUTING.md) for more information.
		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/registry/blob/main/CONTRIBUTING.md) for more information.