MCP

You can add additional tools using MCP (Model Context Protocol) 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.

For most use cases, we recommend bundling MCP servers in 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:

$ 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—command/args/env for local servers, url/headers for remote. In configuration files, set amp.mcpServers and use ${VAR_NAME} syntax for environment variables:

"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. For servers requiring manual auth, pass headers directly or use manual OAuth registration.

Amp ID Tokens

In an orb, a remote server can authenticate the thread with an Amp ID token. Put ${amp:id-token} in a header:

"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. 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.”

Remote MCP Definitions

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:

$ 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:

$ 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

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

$ 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:

$ 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 Amp Workload Identity 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} 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. 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 Edit, and edit ID. 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.

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 runner reloads that runner’s local configuration; it does not force all threads to refresh their remote catalogs.

Controlling Remote Tools

To control how agents use each of a remote server’s tools, expand Tools on the server in MCP settings and choose a policy from the menu next to each tool:

• Allow: agents can call the tool without your approval. This is the default, including for tools the server adds later.
• Ask First: 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.
• Disabled: 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. 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 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

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 off for you, but only you can turn it back on, in MCP settings.

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

Local MCP Server Loading Order

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.

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:

$ 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 Servers in Orbs

Local (stdio) and remote MCP servers both work in 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 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 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, or in the workspace’s settings for workspace approvals.
• Add remote MCP definitions in your MCP server settings. 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, send an 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.

MCP Best Practices

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

• Bundle MCP servers in 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 Local MCP Configuration

Many MCP servers, like Linear, 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.

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

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

$ amp mcp oauth logout my-server