agent add mcp
- Repo stars 59,731
- Author repo warp
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @warpdotdev · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Required · Vendor-specific
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
If the user hasn't specified, ask whether they want to configure the server globally (for all projects) or project-scoped (for a specific repository only). Config file paths: Global (user-scoped): `~/.warp/.mcp.json` Project-scoped: `{repo_root}/.warp/.mcp.json`
If the user hasn't provided the server's connection details, use WebSearch to find the correct configuration for the named server. If it's unclear whether the server should be run as a local CLI process (stdio transport) or connected to via URL (HTTP/SSE streaming transport), ask the user which they prefer.
Check whether the target config file exists. If it does not exist, create it with `mkdir -p` for the directory and initialize it with an empty `mcpServers` wrapper key: If it exists, read it to determine which top-level wrapper key is already in use. Recognized wrapper keys (in order of preference): `mcpServers` *(preferred)* `mcp_servers`
Step 4: Write the Server Configuration
# Adding MCP Servers to Warp
Warp supports MCP servers via native config files. Follow these steps when helping a user add an MCP server.
## Step 1: Determine Scope
If the user hasn't specified, ask whether they want to configure the server **globally** (for all projects) or **project-scoped** (for a specific repository only).
Config file paths:
- **Global (user-scoped):** `~/.warp/.mcp.json`
- **Project-scoped:** `{repo_root}/.warp/.mcp.json`
## Step 2: Gather Server Details
If the user hasn't provided the server's connection details, use WebSearch to find the correct configuration for the named server.
If it's unclear whether the server should be run as a local CLI process (stdio transport) or connected to via URL (HTTP/SSE streaming transport), ask the user which they prefer.
## Step 3: Check and Prepare the Config File
Check whether the target config file exists.
- **If it does not exist**, create it with `mkdir -p` for the directory and initialize it with an empty `mcpServers` wrapper key:
```json
{
"mcpServers": {}
}
```
- **If it exists**, read it to determine which top-level wrapper key is already in use. Recognized wrapper keys (in order of preference):
- `mcpServers` *(preferred)*
- `mcp_servers`
- `servers`
- `mcp.servers` (nested under a `mcp` key)
- Flat map (each top-level key is a server name)
Preserve the existing wrapper key when writing. If the existing key is unrecognized or incompatible, switch to `mcpServers`.
**Never remove existing server entries** — only add or update the new server.
## Step 4: Write the Server Configuration
### Command-based server (stdio transport)
```json
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "@scope/package-name"],
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
```
By default, Warp spawns stdio servers from the directory the config was discovered in:
- Project-scoped configs (`{repo_root}/.warp/.mcp.json`) run from the repo root.
- Global configs (`~/.warp/.mcp.json`, `~/.claude.json`, etc.) run from the home directory.
If the server's `command` or `args` are relative paths (e.g. `./tooling/mcp/server.js`) or the server expects a specific cwd, set `working_directory` to override the default:
```json
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["./tooling/mcp/server.js"],
"working_directory": "/absolute/path/to/repo"
}
}
}
```
### URL-based server (HTTP/SSE streaming transport)
```json
{
"mcpServers": {
"server-name": {
"url": "https://example.com/mcp",
"env": {
"API_KEY": "${API_KEY}"
}
}
}
}
```
For environment variables containing secrets, use `${VAR_NAME}` syntax — Warp will substitute the value from the user's environment at runtime.
## Notes
- Warp auto-detects changes to `.mcp.json` files on save — no restart required.
- Configured servers appear in Warp's Settings under MCP, labeled **"Detected from Warp"**.
- Global config applies across all sessions; project config only applies when working inside that repository.
Listed in source order.
sections -> Step 1: Determine Scope → Step 2: Gather Server Details → Step 3: Check and Prepare the Config File → Step 4: Write the Server Configuration → Command-based server (stdio transport) → URL-based server (HTTP/SSE streaming transport)
terms -> globally · project-scoped · Global (user-scoped) · Project-scoped · If it does not exist · If it exists · Never remove existing server entries · "Detected from Warp"
files/cmd -> ~/.warp/.mcp.json · {repo_root}/.warp/.mcp.json · mkdir -p · mcpServers · mcp_servers · servers · mcp.servers · mcp
body sha256 -> 8dd798c0826d
Step 1: Determine Scope
If the user hasn't specified, ask whether they want to configure the server globally (for all projects) or project-scoped (for a specific repository only). Config file paths: Global (user-scoped):
~/.warp/.mcp.jsonProject-scoped:{repo_root}/.warp/.mcp.jsonStep 2: Gather Server Details
If the user hasn't provided the server's connection details, use WebSearch to find the correct configuration for the named server. If it's unclear whether the server should be run as a local CLI process (stdio transport) or connected to via URL (HTTP/SSE streaming transport), ask the user which they prefer.
Step 3: Check and Prepare the Config File
Check whether the target config file exists. If it does not exist, create it with
mkdir -pfor the directory and initialize it with an emptymcpServerswrapper key: If it exists, read it to determine which top-level wrapper key is already in use. Recognized wrapper keys (in order of preference):mcpServers(preferred)mcp_serversCommand-based server (stdio transport)
By default, Warp spawns stdio servers from the directory the config was discovered in: Project-scoped configs (
{repo_root}/.warp/.mcp.json) run from the repo root. Global configs (~/.warp/.mcp.json,~/.claude.json, etc.) run from the home directory. If the server'scommandorargsare relative paths (e.g../tooling/mcp/server.js) or the server expects a specific cwd, setworking_directoryto override the default:URL-based server (HTTP/SSE streaming transport)
For environment variables containing secrets, use
${VAR_NAME}syntax — Warp will substitute the value from the user's environment at runtime.