# MCP

You can add additional tools using [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers, which can be either local or remote.

For most use cases, we recommend [bundling MCP servers in skills](#agent-skills) via `mcp.json` instead of adding them to your user settings. This keeps the tool list clean and loads MCP tools only when needed.

If loading the MCP via skills isn't suitable (if it must be always available in the context window), add it via the CLI or in your [configuration file](#configuration):

```shell-session
$ amp mcp add context7 -- npx -y @upstash/context7-mcp
$ amp mcp add linear https://mcp.linear.app/sse
```

MCP servers use the same configuration fields as [MCP servers in skills](#agent-skills)—`command`/`args`/`env` for local servers, `url`/`headers` for remote. In configuration files, set `amp.mcpServers` and use `$` syntax for environment variables:

```json
"amp.mcpServers": {
    "playwright": {
        "command": "npx",
        "args": ["-y", "@playwright/mcp@latest", "--headless"]
    },
    "linear": {
        "url": "https://mcp.linear.app/sse"
    },
    "sourcegraph": {
        "url": "${SRC_ENDPOINT}/.api/mcp/v1",
        "headers": { "Authorization": "token ${SRC_ACCESS_TOKEN}" }
    }
}
```

Many remote servers handle authentication automatically via [OAuth](#mcp-oauth). For servers requiring manual auth, pass headers directly or use [manual OAuth registration](#mcp-oauth).

#### MCP Server Loading Order

When the same MCP server name appears in multiple places, Amp uses this precedence (highest to lowest):
1. CLI flags (`--mcp-config`)
2. User/workspace config (`amp.mcpServers`)
3. Skills (only loaded if not already configured above)

This means you can override skill-provided MCP servers with your own configuration if needed.

#### Workspace MCP Server Trust

MCP servers in workspace settings (`.amp/settings.json`) require explicit approval before they can run. This prevents untrusted code from executing automatically when you open a project.

When a workspace MCP server is awaiting approval, you'll see `awaiting approval` in `amp mcp doctor` output. To approve:

```shell-session
$ amp mcp approve my-server
```

In the CLI, you'll be prompted to approve workspace servers when they're first detected.

MCP servers in your global settings (`~/.config/amp/settings.json`) or passed via `--mcp-config` do not require approval.

#### MCP Best Practices

Too many available tools can reduce model performance, so for best results, be selective:
- [Bundle MCP servers in skills](#agent-skills) instead of adding them globally—tools stay hidden until the skill loads.
- Use MCP servers that expose a small number of high-level tools with high-quality descriptions.
- Disable MCP tools you aren't using, or consider using CLI tools instead.

#### OAuth for Remote MCP Servers

Some MCP servers like [Linear](https://linear.app/changelog/2025-05-01-mcp) support automatic OAuth client registration. When you add such a server, Amp will automatically start the OAuth flow in your browser upon startup.

**Manual OAuth Client Registration**

For servers that require manual OAuth client configuration:

1. Create an OAuth client in the server's admin interface with:
   - Redirect URI: `http://localhost:8976/oauth/callback`
   - Required scopes for your use case

2. Add the MCP server to your configuration:

```shell-session
$ amp mcp add my-server https://example.com/.api/mcp/v1
```

3. Register your OAuth credentials:

```shell-session
$ amp mcp oauth login my-server \
  --server-url https://example.com/.api/mcp/v1 \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --scopes "openid,profile,email,user:all"
```

Upon startup, Amp will open your browser to complete the authentication flow.

OAuth tokens are stored securely in `~/.amp/oauth/` and are automatically refreshed when needed.

If a provider-side token becomes stale or is revoked, clear stored OAuth credentials and let Amp
reauthenticate on next startup:

```shell-session
$ amp mcp oauth logout my-server
```