MCP server specs
MCP servers
Pure YAML, no markdown body, one file per server.
name: filesystem
description: Local filesystem access for the model.
type: stdio
command: npx
args:
- -y
- "@modelcontextprotocol/server-filesystem"
env:
ROOT: /tmp
name is the server identifier, not the filename. It may contain package-style slashes, such as npm:@modelcontextprotocol/server-sequential.thinking. Such names are percent-encoded in YAML filenames and kept as-is in every generated config. Other spec kinds need one safe path segment, because their names become output paths.
A server needs command (stdio) or url (remote). agnostic-ai lint reports a missing one as LINT008; validate and sync do not, and some targets write a server that cannot start. See lint.
| Field | Required | Default | Description |
|---|---|---|---|
name | yes | none | Server identifier and key in the generated config. |
description | no | empty | Free-form documentation. Dropped where the target's MCP schema has no such key (Junie, Warp). |
type | no | stdio | stdio, http, sse, or ws. Remote transports write an explicit type; stdio stays implicit. A ws entry emits no server on Augment, Factory, and Qoder. |
command | stdio only | none | Executable to launch. |
args | no | empty | Argument list for the command. |
env | no | empty | Environment variables for the server. |
url | http/sse/ws only | none | Endpoint URL. |
headers | no | empty | HTTP headers for http/sse. |
cwd | no | empty | Working directory for a stdio server, where supported. |
timeout | no | empty | Units vary by target: milliseconds on most. |
oauth | no | empty | OAuth settings. The shape is target-specific; see the target page. |
disabled | no | false | See disabled support by target. |
roots | no | empty | List of {uri, name} objects, for targets that support MCP roots. |
These fields apply only to the listed targets and are ignored elsewhere.
| Target | Extra fields |
|---|---|
| Codex | env_vars, env_http_headers, http_headers_helper, auth, required, startup_timeout_sec, startup_timeout_ms, tool_timeout_sec, default_tools_approval_mode, scopes, oauth_resource, experimental_environment, enabled_tools, disabled_tools |
| Crush | enabled_tools, disabled_tools, sessionless |
| Gemini | trust, includeTools, excludeTools |
| Qoder | trust, includeTools, excludeTools, alwaysAllow |
| Kiro | autoApprove, disabledTools, oauthScopes |
| Factory | disabledTools, connectTimeout |
| Claude Code | alwaysLoad, headersHelper |
| Cursor | envFile, auth |
| Copilot / VS Code | envFile, dev, sandboxEnabled (VS Code file only), tools (Copilot CLI files only) |
| Continue | connectionTimeout, requestOptions |
| OpenHands | auth: oauth, or a truthy oauth, which sets auth: "oauth" on a remote server in ~/.openhands/mcp.json |
On Amp, set x-amp.includeTools. Use x-factory, x-kilo, or x-continue to override the matching top-level options for that target.
disabled support by target
Only the targets listed were checked.
| Target | Behavior |
|---|---|
| Antigravity, Crush, Factory, Kiro, Qoder, Windsurf | Native disabled |
| Codex | Mapped to enabled = false |
| Kilo Code, OpenCode, Zed | Mapped to "enabled": false |
| Copilot | A disabledMcpServers entry in .github/copilot/settings.json for Copilot CLI. Stripped from both MCP files with a note; disable the server in VS Code for that half |
| Claude Code | Mapped to project disabledMcpjsonServers in .claude/settings.json for servers emitted to .mcp.json. Import restores it |
| Cursor, Augment, Junie, Trae, Warp | Stripped with a note. Disable the server in the tool itself |