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.

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.

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

To share an existing personal definition, open its menu in personal MCP settings and select

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.

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.

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.

Renaming a server does not change its ID. To change the ID, open the server’s menu in 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.

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.

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

Orbs run their own Amp executor in a fresh environment, so MCP servers configured in the settings file on your machine are not available there. To use MCP servers in orbs:

• 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 inside the orb before they run.
• 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, 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

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

$ 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