---
lastModified: 2026-09-28
---

# MCP

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

Amp has two ways to configure these servers:

- Local MCP configuration is stored in `amp.mcpServers`. A URL entry is still local configuration,
  even when the URL points to another machine.
- Remote MCP definitions are stored by ampcode.com. You can manage them in MCP server settings or
  with `amp mcp remote`.

For most use cases, we recommend [bundling MCP servers in skills](/docs/customize/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 server 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](/docs/cli/settings):

```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](/docs/customize/skills#mcp-servers-in-skills)—`command`/`args`/`env` for
local servers, `url`/`headers` for remote. In configuration files, set `amp.mcpServers` and use
`${VAR_NAME}` 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).

<h3 id="mcp-amp-id-token">Amp ID Tokens</h3>

In an [orb](/docs/orbs), a remote server can authenticate the thread with an Amp ID token. Put
`${amp:id-token}` in a header:

```json
"amp.mcpServers": {
    "internal-tools": {
        "url": "https://mcp.example.com/mcp",
        "headers": { "Authorization": "Bearer ${amp:id-token}" }
    }
}
```

Amp sends the same token that `amp orb id-token --audience https://mcp.example.com` prints. The
audience is the HTTPS origin of the server URL, including a nondefault port but not the path or
query. Amp mints the token before it connects, sends it only to that origin, rejects redirects, and
replaces it before it expires. If the server returns 401 while connecting, the connection fails and
Amp does not retry it. If the token exchange fails, Amp retries the connection. Amp removes the
token from server error messages before it logs them. The server must verify the token as
described in [Handling Secrets](/docs/orbs/handling-secrets#oidc). The token contains
`token_use: "exchanged"`.

`${amp:id-token}` works only in headers of HTTPS servers without OAuth configuration. Amp rejects it
in URLs and in the command, arguments, and environment of local servers. A local server that needs
a token can run `amp orb id-token` itself. Outside an orb, the server fails to connect with
"`${amp:id-token}` requires an Amp orb."

<h2 id="remote-mcp-definitions">Remote MCP Definitions</h2>

Remote MCP definitions are available across Amp clients without a local settings file. Store one
definition in your personal settings, a workspace, or a project:

```shell-session
$ amp mcp remote --personal add Linear https://mcp.linear.app/mcp
$ amp mcp remote --workspace acme add Linear https://mcp.linear.app/mcp
$ amp mcp remote --project acme/app add Linear https://mcp.linear.app/mcp
```

To share an existing personal definition, open its menu in personal MCP settings and select
<span class="ui">Copy to Workspace</span>. Amp pre-fills the server URL, name, authentication type,
and OAuth client ID. When you save, Amp securely copies its stored bearer token or OAuth client
secret on the server. The credential never appears in the page URL or form. Existing OAuth
sign-ins remain personal and are not copied.

Every `amp mcp remote` command needs one scope option. Use `--personal`,
`--workspace <workspace>`, `--project <project>`, or `--current-project`. You can put the scope
before or after the command. `--current-project` selects the Amp project that matches the current
repository.

Amp detects authentication when you omit `--auth`. You can also select an authentication type:

```shell-session
$ amp mcp remote add Public https://mcp.example.com/mcp --auth none --current-project
$ amp mcp remote add Private https://mcp.example.com/mcp --auth bearer --bearer-token-file /path/to/token --workspace acme
$ amp mcp remote add OAuth https://mcp.example.com/mcp --auth oauth --personal
$ amp mcp remote add OAuth https://mcp.example.com/mcp --auth oauth --oauth-client-id <id> --oauth-client-secret-file /path/to/secret --workspace acme
```

For OAuth without client options, Amp uses credentials configured by the Amp server or the
provider's automatic client setup. If the Amp server has marked a provider as unsupported, the
command prints the provider's notice and does not add the definition.

Use a server name or UUID to update, remove, check, list tools, log in, or log out. The UUID is
the `id` returned by `amp mcp remote list --json`, not the editable ID in MCP settings. Names are
matched without case sensitivity within the selected scope:

```shell-session
$ amp mcp remote --personal list
$ amp mcp remote --personal update Linear --disabled
$ amp mcp remote --personal check Linear
$ amp mcp remote --personal tools Linear --refresh
$ amp mcp remote --personal login Linear
$ amp mcp remote --personal logout Linear
$ amp mcp remote --personal remove Linear --yes
```

Add `--json` to any of these commands for structured output. Pass bearer tokens and OAuth client
secrets through `--bearer-token-file <path>` or `--oauth-client-secret-file <path>`. Use `-` as the
path to read one secret from standard input. Amp does not accept these secret values as command
arguments.

### Amp Workload Identity

With access granted by Amp staff, select <span class="ui">Amp Workload Identity</span> in the
server's authentication menu, or use `--auth workload-identity` with `amp mcp remote add`.
This applies to remote definitions stored by Amp, not local `amp.mcpServers` or skill configuration.
For those, use [`${amp:id-token}`](#mcp-amp-id-token) in orbs.
Both the person configuring the server and each thread owner using it need access.

Amp sends a fresh, five-minute RS256 JWT as a Bearer token. The issuer is
`https://ampcode.com/api/workload-identity`, with public keys at that issuer's `/jwks.json`.
The audience is the normalized HTTPS origin of the configured MCP URL, including a nondefault
port but excluding its path and query. For `https://mcp.example.com/mcp`, it is
`https://mcp.example.com`. There is no audience override. Redirects are rejected.

The token contains `user_id` and `thread_id`, plus `workspace_id` and `project_id` when present.
It also contains these authoritative collaboration claims, captured when the token is issued:

- `thread_visibility`: the effective sharing mode: `private`, `thread_group_shared`,
  `thread_workspace_shared`, or `public_unlisted`.
- `thread_multiplayer`: whether the thread has an active multiplayer window.
- `thread_non_owner_can_influence`: whether a non-owner workspace member can currently influence
  the thread through multiplayer. Public unlisted viewers cannot influence the thread.

The subject uses the same thread hierarchy as orb workload identity, e.g.
`workspace:<id>:project:<id>:user:<id>:thread:<id>`. It also contains `token_use: "mcp"` and a unique
`jti`. It does not include the user's email. The identity is the thread owner's, including in
shared threads, not the identity of whoever sent the latest message. Amp does not currently add an
initiating user or run claim because the token request does not authoritatively identify either.

The MCP server must verify the signature, issuer, exact audience, and expiry, then authorize
the identity claims. A valid Amp signature alone is not permission to use your server. The origin
is the trust boundary, so do not host mutually untrusted MCP tenants on different paths of the
same origin. Treat tokens as secrets and never return them in tool results or log them.

Amp discovers tools separately in each thread and does not save these tool lists in the shared
settings cache. Settings cannot test the connection because they have no thread identity.
No OAuth sign-in or stored credential is needed. Amp checks access before issuing each token.
Disabling the server or removing access prevents new tokens; already issued tokens can remain
valid for up to five minutes.

### Remote Server IDs and Overrides

Each remote server has an ID, initially generated from its name. This ID is only used to decide
which servers override each other across settings.

IDs must be unique within your
personal settings, within each workspace, and within each project. Across these settings, project
servers override workspace servers with the same ID, and workspace servers override personal
servers with the same ID. Disabled servers do not override others. Tool discovery also requires
cached tools; a server with no cached tools does not hide another server's tools.
Workload identity servers are an exception. They take precedence before fetching tools within
the thread, so a failed connection does not silently select a less specific server.

Renaming a server does not change its ID. To change the ID, open the server's menu in MCP settings,
choose <span class="ui">Edit</span>, and edit <span class="ui">ID</span>. This preserves its saved
sign-ins and cached tools, but can expose or hide other servers. A workspace or project change can
affect every member's threads, including threads using orbs or local runners.

Running threads refresh their remote tool lists in the background, so they do not all see a change
at once. A running `code_exec` call keeps its selected server UUIDs. Later calls, including calls
retried after a thread actor restarts, use the catalog available when they start. Changing an ID
does not cancel calls already in progress or revoke access to the previously selected server.

Code-mode import names come from server names, not IDs. If an ID change exposes another server with
the same name, import names can gain suffixes such as `buildkite_2`, and an existing import can
refer to a different server. Before changing a shared ID, stop affected threads and coordinate with
workspace members. Afterward, check the servers listed by `tool_search` before resuming work. Give
servers distinct names when you need to distinguish them in tool discovery.

Remote ID edits do not restart runners or change local `amp.mcpServers` configuration. Reloading
MCP in a runner reloads that runner's local configuration; it does not force all threads to refresh
their remote catalogs.

### Structured remote tool results

Amp discovers saved remote MCP tools with `tool_search` and calls them through `code_exec`.
When a tool declares an `outputSchema`, Amp includes its return type in tool discovery and
validates successful `structuredContent` against that schema for normal calls. Missing or
mismatched structured results produce a catchable JavaScript error. Validation errors include
the failing field and constraint when available, plus a bounded preview of the returned data.
Tool error results (`isError: true`) are exempt from schema validation.

An imported function returns `structuredContent` when present, including arrays, `null`, and
other JSON values. Otherwise, it returns the tool's text, parsed as JSON when that text contains
an object or array. Normal calls throw on tool errors.

Call the function's `.raw(input)` method instead to receive the complete MCP result, including
responses that violate the output schema or report a tool error. Raw calls skip output-schema
validation, but network and authentication failures still produce errors.

When the server returns both structured data and text, a single raw call preserves both in
`result.structuredContent` and `result.content`. Text blocks have `type: "text"` and a `text`
field. Resource links and other content blocks are preserved too.

A raw call invokes the tool once; it does not retrieve the result of an earlier call. Use a
single raw call when you need both forms. After an error, inspect its preview rather than
repeating an operation with side effects just to obtain the raw response.

These rules apply to remote MCP definitions saved on ampcode.com, not to executor MCP servers
configured through `amp.mcpServers`.

<h2 id="mcp-loading-order">Local MCP Server Loading Order</h2>

For local configuration, when the same MCP server name appears in multiple places, Amp uses this
precedence (highest to lowest):

1. CLI flags (`--mcp-config`)
2. Workspace config (`amp.mcpServers` in `.amp/settings.json`)
3. User config (`amp.mcpServers` in `~/.config/amp/settings.json`)
4. Skills

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

<h2 id="mcp-trust">Workspace MCP Server Trust</h2>

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.

<h2 id="mcp-in-orbs">MCP Servers in Orbs</h2>

Local (stdio) and remote MCP servers both work in [orbs](/docs/orbs). An orb runs its own Amp
executor on a separate machine, so it does not read the settings file on your computer, such as
`~/.config/amp/settings.json`. Configure the servers where the orb can see them:

- [Bundle them in skills](/docs/customize/skills#mcp-servers-in-skills) via `mcp.json` committed to
  the repository (recommended).
- Commit them to the repository's workspace config (`amp.mcpServers` in `.amp/settings.json`).
  Workspace servers require [approval](#mcp-trust) inside the orb before they run.
- Add remote MCP definitions in your [MCP server settings](/settings/mcp-servers). They are
  available in orb threads without repository changes.

Browser-based OAuth flows are unavailable in orbs. For remote servers that need authentication,
pass tokens via `headers` using environment variables from
[secrets settings](/docs/orbs/handling-secrets), send an [Amp ID token](#mcp-amp-id-token), or use
remote MCP definitions, which handle OAuth through ampcode.com. Run `amp mcp remote login` to print
the ampcode.com OAuth URL.

<h2 id="mcp-best-practices">MCP Best Practices</h2>

Too many available tools can reduce model performance, so for best results, be selective:

- [Bundle MCP servers in skills](/docs/customize/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](/docs/cli/settings), or consider using CLI tools instead.

<h2 id="mcp-oauth">OAuth for Local MCP Configuration</h2>

Some MCP servers like [Linear](https://linear.app/changelog/2025-05-01-mcp) support automatic OAuth
client registration. When you start the Amp TUI after adding a URL entry to `amp.mcpServers`, Amp
will automatically start the OAuth flow in your browser. The `amp mcp oauth` commands manage this
local OAuth state. Use `amp mcp remote login` and `amp mcp remote logout` for remote MCP definitions
stored by ampcode.com.

On a runner started with `amp --no-tui`, a server that needs OAuth asks for sign-in in a dialog in an
attached thread on ampcode.com. If no thread is attached yet, the runner asks once a thread
attaches. If you open the sign-in link in a browser on the runner's machine, sign-in finishes on its
own. From any other device, the browser ends on a `localhost` page that fails to load. Copy that
page's full URL and paste it into the dialog. The runner exchanges the code and keeps the tokens in
its own secret storage, so the MCP server and its sign-in provider only need to be reachable from the
runner's network.

<details>
<summary><strong>Manual OAuth Client Registration</strong></summary>

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"
```

When you start the Amp TUI, Amp will open your browser to complete the authentication flow.

OAuth tokens are stored securely in Amp's secret storage 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
```

</details>