---
lastModified: 2026-11-19
---

# 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`. Amp's servers connect to them, so a server that accepts only known IP
  addresses must allow [Amp's server IP addresses](/docs/egress-ips).

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

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.

Some servers need more headers on every request, such as an organization ID. Add them under
<span class="ui">Headers</span> when you add or edit a definition in
[MCP server settings](/settings/integrations). Amp sends them with every authentication type. Mark
a header <span class="ui">Secret</span> when its value is a credential. Amp checks it for you when
the name or value looks like one, such as `X-Api-Key` or `Bearer …`. Amp encrypts secret values
and never shows them again; leave one blank to keep it. A saved secret header stays secret; to
make it non-secret, remove it and add it again. When you change the server URL, enter each secret
value again. Other header values stay visible in settings. To add several headers at once, choose
<span class="ui">Paste Headers</span> and paste `Name: value` lines; Amp marks the likely secrets.

From the CLI, pass `--headers` to `add` or `update` with JSON `[name, value]` pairs, and
`--secret-headers` with comma-separated names of secret headers, the same as
[model routing](/docs/customize/model-routing). Without `--secret-headers`, stored headers keep
their setting and new headers are secret when they look like credentials. On `update`,
`--headers` replaces every stored header; an empty value keeps the stored value, and `'[]'`
removes them all:

```bash
$ amp mcp remote --personal add SonarQube https://api.sonarcloud.io/mcp --auth bearer --bearer-token-file /path/to/token --headers '[["SONARQUBE_ORG","acme"]]'
```

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

In a thread, the agent does the same with the `manage_amp` tool and topic `remote_mcp_servers`.

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

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.

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` (only the owner),
  `thread_group_shared` (specific workspace groups or members), `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. Disabling the server 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. Agents import the server's tools
under this ID: `tool_search` lists the server as a module with this name, and `code_exec` imports
from it. The ID also decides 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 in Integrations & 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.

Amp saves each remote server's tool list. When a thread loads a list that is more than a day old,
Amp fetches it again from the server in the background, so tools the server adds or removes reach
threads without anyone refreshing them. Reloading MCP in a thread fetches such lists before it
returns. To pick up tools added within the last day, choose <span class="ui">Refresh Tools</span>
on the server in settings or run `amp mcp remote tools <server> --refresh` with the server's scope
option.

A thread loads its remote tool list when its thread actor starts. While the thread actor runs, it
loads the list again when someone adds, edits, or removes a remote server that applies to the
thread, when a refresh finds that a server's tools changed, and when MCP is reloaded in that
thread, either by the `reload_mcp` tool or by the Reload MCP command. A thread actor that is asleep
loads the current list when it wakes. 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.

Changing an ID changes the module name in `tool_search` and `code_exec` imports. Code that imports
the old ID stops working. If an ID change makes this server override another one, imports of that
ID refer to this server instead. Before changing a shared ID, stop affected threads and coordinate
with workspace members. Afterward, check the servers listed by `tool_search` before resuming work.

Remote ID edits do not restart runners or change local `amp.mcpServers` configuration. Reloading
MCP in a thread reloads its executor's local configuration and that thread's remote tool list; it
does not refresh other threads.

### Controlling Remote Tools

To control how agents use each of a remote server's tools, expand <span class="ui">Tools</span> on
the server in MCP settings and choose a policy from the menu next to each tool:

- <span class="ui">Allow</span>: agents can call the tool without your approval. This is the
  default, including for tools the server adds later.
- <span class="ui">Ask First</span>: agents ask the thread owner to approve each call. When code in
  `code_exec` calls the tool, Amp shows the owner the tool and its input, and the code waits, and the
  thread may sleep, until the owner approves or declines, so a thread that runs unattended stops at
  the call. Subagents cannot wait for an answer, so they cannot call these tools. MCP Apps can still
  call these tools, since a person is looking at the app.
- <span class="ui">Disabled</span>: the tool is hidden from `tool_search`, and neither agents nor
  MCP Apps can call it.

The thread records each answer below the `code_exec` call: the tool, whether it was approved or
declined, the user ID of the person who answered, and the time. The agent does not see this
record.

A server can require a person to approve every call to one of its tools by setting
`"anthropic/requiresUserInteraction": true` in the tool's `_meta`, as in
[Claude Code](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool). Amp treats
such a tool as Ask First: you can disable it, but you cannot allow it.

Policies apply in every thread, including threads in orbs. Amp checks a tool's policy each time
the tool is called, so a change applies right away, even in threads that are already running.

You can set policies on your personal servers. Workspace admins can set them on workspace servers,
and project managers on project servers. You can also ask Amp to change a tool's policy for you;
Amp asks you to confirm each change in a dialog first. Members see each tool's policy but cannot
change it. A server with every tool disabled still overrides servers with the same ID.

`amp.tools.disable` in local settings does not apply to remote MCP definitions.

### Privacy in Multiplayer Threads

In a [multiplayer](/docs/collaborate/multiplayer) thread, any workspace member can prompt the agent,
and the agent calls remote MCP tools with the thread owner's credentials. To block a server there,
open it in Integrations & MCP settings and turn off
<span class="ui">Use in Multiplayer Threads</span>. It is on by default,
except for new servers for services that reach personal data, such as Slack, Gmail, and Granola.
A server with it off shows a <span class="ui">Not in Multiplayer</span> badge.

While a thread is multiplayer, no one can use the tools of a server with this setting off in that
thread, including the thread owner. The tools work again when multiplayer ends. Amp can turn this
setting on or off for you in a thread that is not multiplayer, after you approve the change in a
dialog.

This guards against accidental use, not a determined contributor. Someone in a multiplayer thread
can still get around it, for example by ending multiplayer, starting a background process that
outlasts it, or creating another thread. It does not apply to local servers from `amp.mcpServers`.

### Questions From Remote Servers

A remote server can ask you for input while one of its tools runs, for example to confirm before
it sends an email. This is MCP
[elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation). Amp
shows the question in a dialog in the thread, and `code_exec` waits until you answer. Amp sends
your answer, or your decline, to the server; the agent sees only the tool's result.

Questions can have text, number, yes or no, and single-choice fields. Links in the server's text
are not clickable. Amp cancels questions with multiple-choice fields.

A server can also ask you to finish a step on its own web page, such as entering an API key or
connecting an account. Amp shows the page's address and an **Open in Browser** button. What you
enter there goes to the server, not to Amp or the agent. Once you open the page, the button
becomes **Continue**; click it when you are done on the page. Amp opens only `https` pages, or `http` pages on `localhost`.

If you do not answer within 10 minutes, or Amp restarts while the question is open, Amp cancels
the question, and the agent learns that the call's outcome is unknown after a restart. Subagents
cannot wait for an answer, so servers cannot ask questions during their calls.

### 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.

An imported function starts the call right away and returns a promise. Awaiting that promise
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.
When the server reports a tool error or returns an invalid reply, awaiting the promise throws an
`Error` with the full MCP response on `error.response`.

Call `.raw()` on the returned promise, such as `await fn(input).raw()`, to read the complete MCP
result from that same call without running the tool again. `.raw()` resolves with the MCP
response even when `isError` is `true`, and still throws on network or authentication failures.
Wrapping the call in `Promise.all([fn(a), fn(b)])` or `.then(...)` returns a plain promise without
`.raw()`, so call `.raw()` on each tool call before wrapping it, e.g., `Promise.all([fn(a).raw(), fn(b).raw()])`.

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

After an error on a call with side effects, inspect `error.response` and check whether the action
already ran before trying again.

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) before they run. The orb asks in a dialog in
  your thread: **Allow Once** runs the server in this orb only, **Always Allow for Me** also runs
  it in your later orbs, and **Always Allow for Workspace** (workspace admins only) runs it in the
  orbs of every workspace member. Amp stores the "Always" choices with your account and asks again
  when the server's configuration changes. They apply only in orbs, never to the CLI on your own
  machine. Review and remove them under **Allowed Repository MCP Servers** in your
  [Integrations & MCP settings](/settings/integrations), or in the workspace's settings for
  workspace approvals.
- Add remote MCP definitions in your [MCP server settings](/settings/integrations). 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>

Many MCP servers, like [Linear](https://linear.app/changelog/2025-05-01-mcp), need no setup to
sign in. When you start the Amp TUI after adding a URL entry to `amp.mcpServers`, Amp opens the
server's sign-in page in your browser. Amp supports Client ID Metadata Documents (CIMD), and it
falls back to dynamic client registration for servers that do not support CIMD. 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>
