opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 20:51:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add extending-agents, mcp-servers, and usage-insights pages (#23810)

Browse Source 
Adds three new documentation pages for major shipped features that had
no docs, and updates the platform controls index to reflect current
state.

## New pages

### Extending Agents (`extending-agents.md`)

Covers two workspace-level extension mechanisms:
- **Skills** — `.agents/skills/<name>/SKILL.md` directory structure,
frontmatter format, auto-discovery, `read_skill`/`read_skill_file`
tools, size limits, lazy loading
- **Workspace MCP tools** — `.mcp.json` format, stdio and HTTP
transports, tool name prefixing, discovery lifecycle and caching

### MCP Servers (`platform-controls/mcp-servers.md`)

Admin MCP server configuration:
- CRUD via **Agents** > **Settings** > **MCP Servers**
- Four auth modes: none, OAuth2 (with auto-discovery), API key, custom
headers
- Availability policies: `force_on`, `default_on`, `default_off`
- Tool governance via allow/deny lists
- Permission model and secret redaction

### Usage & Insights (`platform-controls/usage-insights.md`)

Three admin dashboards:
- **Usage limits** — spend caps with per-user and per-group overrides,
priority hierarchy, enforcement behavior
- **Cost tracking** — per-user rollup with token breakdowns, date
filtering, per-model and per-chat drill-down

## Updated files

- **`platform-controls/index.md`** — Moved MCP servers, usage limits,
and analytics from "Where we are headed" into "What platform teams
control today" with links to the new pages. Removed the tool
customization roadmap section (now covered by MCP servers page).
- **`manifest.json`** — Added nav entries for all three new pages.

## Resulting nav hierarchy

```
Coder Agents
├── Getting Started
├── Early Access
├── Architecture
├── Models
├── Platform Controls
│   ├── Template Optimization
│   ├── MCP Servers              ← NEW
│   └── Usage & Insights         ← NEW
├── Extending Agents             ← NEW
└── Chats API
```

---

*PR generated with Coder Agents*
This commit is contained in:
Matt Vollmer
2026-03-30 12:46:34 -04:00
committed by GitHub
parent 0880a4685b
commit ca879ffae6
5 changed files with 381 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai-coder/agents/extending-agents.md
+130
View File
@@ -0,0 +1,130 @@
# Extending Agents
Workspace templates can extend the agent with custom skills and MCP tools.
These mechanisms let platform teams provide repository-specific instructions,
domain expertise, and external tool integrations without modifying the agent
itself.
## Skills
Skills are structured, reusable instruction sets that the agent loads on
demand. They live in the workspace filesystem and are discovered
automatically when a chat attaches to a workspace.
### How skills work
Place skill directories under `.agents/skills/` relative to the workspace
working directory. Each directory contains a required `SKILL.md` file and
any supporting files the skill needs.
On the first turn of a workspace-attached chat, the agent scans
`.agents/skills/` and builds an `<available-skills>` block in its system
prompt listing each skill's name and description. Only frontmatter is read
during discovery — the full skill content is loaded lazily when the agent
calls a tool.
Two tools are registered when skills are present:
| Tool | Parameters | Description |
|-------------------|----------------------------------|----------------------------------------------------------|
| `read_skill` | `name` (string) | Returns the SKILL.md body and a list of supporting files |
| `read_skill_file` | `name` (string), `path` (string) | Returns the content of a supporting file |
### Directory structure
```text
.agents/skills/
├── deep-review/
│ ├── SKILL.md
│ └── roles/
│ ├── security-reviewer.md
│ └── concurrency-reviewer.md
├── pull-requests/
│ └── SKILL.md
└── refine-plan/
└── SKILL.md
```
### SKILL.md format
Each `SKILL.md` starts with YAML frontmatter containing a `name` and an
optional `description`, followed by the full instructions in markdown:
```markdown
---
name: deep-review
description: "Multi-reviewer code review with domain-specific reviewers"
---
# Deep Review
Instructions for the skill go here...
```
### Naming and size constraints
- Names must be kebab-case (`^[a-z0-9]+(-[a-z0-9]+)*$`) and match the
directory name exactly.
- `SKILL.md` has a maximum size of 64 KB.
- Supporting files have a maximum size of 512 KB. Files exceeding the limit
are silently truncated.
### Path safety
`read_skill_file` rejects absolute paths, paths containing `..`, and
references to hidden files. All paths are resolved relative to the skill
directory.
## Workspace MCP tools
Workspace templates can expose custom
[MCP](https://modelcontextprotocol.io/introduction) tools by placing a
`.mcp.json` file in the workspace working directory. The agent discovers
these tools automatically when it connects to a workspace and registers
them alongside its built-in tools.
### Configuration
Define MCP servers in `.mcp.json` at the workspace root. Each entry under
`mcpServers` describes a server. The transport type is inferred from
whether `command` or `url` is present, or you can set it explicitly with
`type`:
```json
{
"mcpServers": {
"github": {
"command": "github-mcp-server",
"args": ["--token", "..."]
},
"my-api": {
"type": "http",
"url": "http://localhost:8080/mcp",
"headers": { "Authorization": "Bearer ..." }
}
}
}
```
**Stdio transport** — set `command`, and optionally `args` and `env`. The
agent spawns the process in the workspace.
**HTTP transport** — set `url`, and optionally `headers`. The agent connects
to the HTTP endpoint from the workspace.
### How discovery works
The agent reads `.mcp.json` via the workspace agent connection on each chat
turn. Discovery uses a 5-second timeout. Servers that fail to
respond are skipped — partial success is acceptable. Empty results are not
cached because the MCP servers may still be starting.
### Tool naming
Tool names are prefixed with the server name as `serverName__toolName` to
avoid collisions between servers and with built-in tools.
### Timeouts
- **Discovery**: 5-second timeout.
- **Tool calls**: 60 seconds per invocation.
docs/ai-coder/agents/platform-controls/index.md
+23 -23
View File
@@ -74,24 +74,31 @@ discoverable descriptions, restricting template visibility, configuring network
boundaries, scoping credentials, and designing template parameters for agent
use.
### MCP servers
Administrators can register external MCP (Model Context Protocol) servers that
provide additional tools for agent chat sessions. This includes configuring
authentication, controlling which tools are exposed via allow/deny lists, and
setting availability policies that determine whether a server is mandatory,
opt-out, or opt-in for each chat.
See [MCP Servers](./mcp-servers.md) for configuration details.
### Usage limits and analytics
Administrators can set spend limits to cap LLM usage per user within a rolling
time period, with per-user and per-group overrides. The cost tracking dashboard
provides visibility into per-user spending, token consumption, and per-model
breakdowns.
See [Usage & Analytics](./usage-insights.md) for details.
## Where we are headed
Coder Agents is in its early stages. The controls above — providers, models,
and system prompt — are what is available today. We are actively building
toward a broader set of platform controls based on what we are hearing from
customers deploying agents in regulated and enterprise environments.
The areas we are investing in include:
### Usage controls and analytics
We plan to give platform teams visibility into how agents are being used across
the organization: token consumption per user, cost per PR, merge rates by model,
and average time from prompt to merged pull request.
The goal is to let platform teams make data-driven decisions — like switching
the default model when analytics show one model produces higher merge rates —
rather than relying on anecdotal feedback from individual developers.
The controls above cover providers, models, system prompts, templates, MCP
servers, and usage limits. We are continuing to invest in platform controls
based on what we hear from customers deploying agents in regulated and
enterprise environments.
### Infrastructure-level enforcement
@@ -107,13 +114,6 @@ Examples of what this looks like:
providers. You can create templates that only permit access to your git
provider and nothing else.
### Tool customization
The agent ships with a standard set of tools (file read/write, shell execution,
sub-agents). We intend to let platform teams customize the available tool set —
adding organization-specific tools or restricting default ones — without
modifying agent source code.
## Why we take this approach
The common pattern in the industry today is that each developer installs and
docs/ai-coder/agents/platform-controls/mcp-servers.md
+125
View File
@@ -0,0 +1,125 @@
# MCP Servers
Administrators can register external MCP servers that provide additional tools
for agent chat sessions. Configured servers are injected into or offered to
users during chat depending on the availability policy.
This is an admin-only feature accessible at **Agents** > **Settings** >
**MCP Servers**.
## Add an MCP server
1. Navigate to **Agents** > **Settings** > **MCP Servers**.
1. Click **Add**.
1. Fill in the configuration fields described below.
1. Click **Save**.
### Identity
| Field | Required | Description |
|----------------|----------|---------------------------------------------------------------|
| `display_name` | Yes | Human-readable name shown to users in chat. |
| `slug` | Yes | URL-safe unique identifier, auto-generated from display name. |
| `description` | No | Brief summary of what the server provides. |
| `icon_url` | No | Emoji or image URL displayed alongside the server name. |
### Connection
| Field | Required | Description |
|-------------|----------|-------------------------------------------------|
| `url` | Yes | The MCP server endpoint URL. |
| `transport` | Yes | Transport protocol. `streamable_http` or `sse`. |
### Availability
| Field | Required | Description |
|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `enabled` | No | Master toggle. Disabled servers are hidden from non-admin users. |
| `availability` | Yes | Controls how the server appears in chat sessions. See [Availability policies](#availability-policies). |
| `model_intent` | No | When enabled, requires the model to describe each tool call's purpose in natural language, shown as a status label in the UI. |
#### Availability policies
| Policy | Behavior |
|---------------|--------------------------------------------------------|
| `force_on` | Always injected into every chat. Users cannot opt out. |
| `default_on` | Pre-selected in new chats. Users can opt out. |
| `default_off` | Available in the server list but users must opt in. |
## Authentication
Each MCP server uses one of four authentication modes. When you change the
auth type, fields from the previous type are automatically cleared.
Secrets are never returned in API responses — boolean flags indicate whether
a value is set.
### None
No credentials are sent. Use this for servers that do not require
authentication.
### OAuth2
Per-user authorization. The administrator configures the OAuth2 provider, and
each user independently completes the authorization flow.
**Manual configuration** — provide all three fields together:
| Field | Description |
|--------------------|-----------------------------|
| `oauth2_client_id` | OAuth2 client ID. |
| `oauth2_auth_url` | Authorization endpoint URL. |
| `oauth2_token_url` | Token endpoint URL. |
Optional fields:
| Field | Description |
|------------------------|---------------------------------|
| `oauth2_client_secret` | OAuth2 client secret. |
| `oauth2_scopes` | Space-separated list of scopes. |
**Auto-discovery** — leave `oauth2_client_id`, `oauth2_auth_url`, and
`oauth2_token_url` empty. The server attempts discovery in this order:
1. RFC 9728 — Protected Resource Metadata
1. RFC 8414 — Authorization Server Metadata
1. RFC 7591 — Dynamic Client Registration
Users connect through a popup that redirects through the OAuth2 provider.
Tokens are stored per-user and refreshed automatically. Users can disconnect
via the UI or API to remove stored tokens.
### API key
A static key sent as a header on every request.
| Field | Required | Description |
|------------------|----------|--------------------------------------|
| `api_key_header` | Yes | Header name (e.g., `Authorization`). |
| `api_key_value` | Yes | Secret value sent in the header. |
### Custom headers
Arbitrary key-value header pairs sent on every request. At least one header
is required when this mode is selected.
## Tool governance
Control which tools from a server are available in chat:
| Field | Description |
|-------------------|---------------------------------------------------------------------------------------|
| `tool_allow_list` | If non-empty, only the listed tool names are exposed. An empty list allows all tools. |
| `tool_deny_list` | Listed tool names are always blocked, even if they appear in the allow list. |
## Permissions
| Action | Required role |
|-------------------------------|---------------------------|
| Create, update, or delete | Admin (deployment config) |
| View enabled servers | Any authenticated user |
| OAuth2 connect and disconnect | Any authenticated user |
Non-admin users only see enabled servers. Sensitive fields such as API keys
and client secrets are redacted in API responses.
docs/ai-coder/agents/platform-controls/usage-insights.md
+85
View File
@@ -0,0 +1,85 @@
# Usage and Analytics
Coder provides two admin-only views for monitoring and controlling agent
spend: usage limits and cost tracking.
## Usage limits
Navigate to **Agents** > **Settings** > **Limits**.
Usage limits cap how much each user can spend on LLM usage within a rolling
time period. When enabled, the system checks the user's current spend before
processing each chat message.
### Configuration
- **Enable/disable toggle** — master on/off for the entire limit system.
- **Period** — `day`, `week`, or `month`. Periods are UTC-aligned: midnight
UTC for daily, Monday start for weekly, first of the month for monthly.
- **Default limit** — deployment-wide default in dollars. Applies to all
users who do not have a more specific override. Leave unset for no limit.
- **Per-user overrides** — set a custom dollar limit for an individual user.
Takes highest priority.
- **Per-group overrides** — set a limit for a group. When a user belongs to
multiple groups, the lowest group limit applies.
### Priority hierarchy
The system resolves a user's effective limit in this order:
1. Individual user override (highest priority)
1. Minimum group limit across all of the user's groups
1. Global default limit
1. No limit (if limits are disabled or no value is configured)
### Enforcement
- Checked before each chat message is processed.
- When current spend meets or exceeds the limit, the chat returns a
**409 Conflict** response and the message is blocked.
- Fail-open: if the limit query itself fails, the message is allowed
through.
- Brief overage is possible when concurrent messages are in flight, because
cost is determined only after the LLM returns.
### User-facing status
Users can view their own spend status, including whether a limit is active,
their effective limit, current spend, and when the current period resets.
> [!NOTE]
> The admin configuration page shows the count of models without pricing
> data. Models missing pricing cannot be tracked accurately against limits.
## Cost tracking
Navigate to **Agents** > **Settings** > **Usage**.
This view shows deployment-wide LLM chat costs with per-user drill-down.
### Top-level view
A per-user rollup table with the following columns:
| Column | Description |
|--------------------|-------------------------------------|
| Total cost | Aggregate dollar spend for the user |
| Messages | Number of chat messages sent |
| Chats | Number of distinct chat sessions |
| Input tokens | Total input tokens consumed |
| Output tokens | Total output tokens consumed |
| Cache read tokens | Tokens served from cache |
| Cache write tokens | Tokens written to cache |
The table supports date range filtering (default: last 30 days), search by
name or username, and pagination.
### Per-user detail view
Select a user to see:
- **Summary cards** — total cost, token breakdowns, and message counts.
- **Usage limit progress** — if a limit is active, a color-coded progress
bar shows current spend relative to the limit.
- **Per-model breakdown** — table of costs and token usage by model.
- **Per-chat breakdown** — table of costs and token usage by chat session.
docs/manifest.json
+18
View File
@@ -1238,9 +1238,27 @@
"description": "Best practices for creating templates that are discoverable and useful to Coder Agents",
"path": "./ai-coder/agents/platform-controls/template-optimization.md",
"state": ["early access"]
},
{
"title": "MCP Servers",
"description": "Configure external MCP servers that provide additional tools for agent chat sessions",
"path": "./ai-coder/agents/platform-controls/mcp-servers.md",
"state": ["early access"]
},
{
"title": "Usage \u0026 Analytics",
"description": "Spend limits and cost tracking for Coder Agents",
"path": "./ai-coder/agents/platform-controls/usage-insights.md",
"state": ["early access"]
}
]
},
{
"title": "Extending Agents",
"description": "Add custom skills and MCP tools to agent workspaces",
"path": "./ai-coder/agents/extending-agents.md",
"state": ["early access"]
},
{
"title": "Chats API",
"description": "Programmatic access to Coder Agents via the experimental Chats API",