Amp

CLI

Sourcegraph

The frontier coding agent for your terminal and editor, with multi-model modes, threads, subagents, and the Oracle.

MCP

Supported

MCP servers configured under amp.mcpServers in settings, added via `amp mcp add`, or bundled inside skills via mcp.json (the recommended approach to keep the tool list clean).

Verified 2026-07-12Docs

Transportsstdiossehttp

Authoauthheadersenv

Config files

Path	Scope	Format	Key
`~/.config/amp/settings.json`	Global	json	amp.mcpServers
`.amp/settings.json` Workspace servers require explicit user approval before running.	Project	json	amp.mcpServers
`.agents/skills/<name>/mcp.json` Skill-bundled servers; tools are hidden until the skill is loaded.	Project	json	—

Fields

Field	Type	Description
`command`	string	Command to run a local (stdio) server.
`args`	string[]	Arguments passed to the command.
`env`	record<string, string>	Environment variables for local servers. Supports ${VAR_NAME} interpolation in settings files.
`url`	string	Endpoint of a remote server.
`headers`	record<string, string>	HTTP headers sent with requests to remote servers (e.g. Authorization).
`includeTools`	string[]	Tool names or glob patterns to filter which tools are exposed (recommended, skill-bundled mcp.json).

Capabilities

ToolsSupported

Examples

amp.mcpServers in settings.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}" }
  }
}

Skill-bundled mcp.json

{
  "chrome-devtools": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest"],
    "includeTools": ["navigate_*", "take_screenshot", "click", "fill*"]
  }
}

•Amp recommends bundling MCP servers in skills via an mcp.json file in the skill directory; servers start with Amp but tools stay hidden until the skill loads.
•Precedence when a server name appears in multiple places: --mcp-config CLI flag > amp.mcpServers in user/workspace settings > skill-bundled servers.
•MCP servers in workspace settings (.amp/settings.json) require explicit approval (`amp mcp approve <name>`) before they can run; global settings and --mcp-config do not.
•OAuth tokens are stored in ~/.amp/oauth/ and refreshed automatically; manage with `amp mcp oauth login|logout`.
•amp.mcpPermissions rules can allow or reject servers matching command/args or url patterns.

Skills

Supported

SKILL.md skills (Agent Skills format) that the agent invokes automatically. Skills can bundle resources and MCP servers (mcp.json) in the skill directory.

Verified 2026-07-12Docs

Invokeautomatic

Config files

Path	Scope	Format	Key
`.agents/skills/<name>/SKILL.md` Project skills, can be committed to git so the team shares them.	Project	markdown	—
`~/.config/agents/skills/<name>/SKILL.md` User-wide skills; ~/.agents/skills/ and ~/.config/amp/skills/ are also scanned.	Global	markdown	—
`.claude/skills/<name>/SKILL.md` Claude Code compatibility path (also ~/.claude/skills/); disable with amp.skills.disableClaudeCodeSkills.	Project	markdown	—

Fields

Field	Type	Description
`name`*	string	Skill identifier. Must be unique; project skills override user-wide, both override built-ins.
`description`*	string	What the skill does. Always visible to the model and determines when it invokes the skill.

Examples

SKILL.md

---
name: my-skill
description: A description of what this skill does
---

# My Skill Instructions

Detailed instructions for the agent...

•User-invokable skills were removed; the model invokes skills based on name and description (see ampcode.com/news/neo).
•Skill precedence (first wins): ~/.config/agents/skills/, ~/.agents/skills/, ~/.config/amp/skills/, .agents/skills/, .claude/skills/, ~/.claude/skills/, then plugins, legacy toolbox directories, and built-in skills.
•name and description are always visible to the model; the SKILL.md body loads on demand when the skill is invoked.
•Skills can bundle MCP servers via an mcp.json file in the skill directory — Amp's recommended way to use MCP.
•amp.skills.path adds extra skill directories; amp.skills.disableClaudeCodeSkills disables loading from Claude Code directories.
•Amp ships a built-in building-skills skill that creates skills tailored to your codebase.

Rules

Supported

AGENTS.md guidance files at project, user, and system scope, with @-file mentions and glob-scoped granular guidance in mentioned files.

Verified 2026-07-12Docs

Invoke@file-mention

Config files

Path	Scope	Format	Key
`AGENTS.md` In cwd, parent dirs, and subtrees. Architecture, build/test commands, conventions.	Project	markdown	—
`~/.config/amp/AGENTS.md` Personal preferences and device-specific guidance; ~/.config/AGENTS.md also works.	Global	markdown	—
`/etc/ampcode/AGENTS.md` System-wide/organization-managed guidance (macOS: /Library/Application Support/ampcode/AGENTS.md, Windows: %ProgramData%\ampcode\AGENTS.md).	Enterprise	markdown	—

Fields

Field	Type	Description
`globs`	string[]	YAML frontmatter in an @-mentioned file; the file is only included once Amp has read a file matching any glob. Globs are implicitly prefixed with **/ unless they start with ./ or ../.

Examples

Glob-scoped guidance file (docs/typescript-conventions.md)

---
globs:
  - '**/*.ts'
  - '**/*.tsx'
---

Follow these TypeScript conventions:

- Never use the `any` type

@-mentions in AGENTS.md

See @doc/style.md and @specs/**/*.md.

When making commits, see @doc/git-commit-instructions.md.

•AGENTS.md in the cwd (or editor workspace roots) and parent directories up to $HOME are always included; subtree AGENTS.md files are included when the agent reads a file in that subtree.
•If no AGENTS.md exists in a directory, AGENT.md or CLAUDE.md is used instead.
•@-mention other files inside agent files to include them as context; relative, absolute, ~/ paths and glob patterns are supported.
•Mentioned files can declare `globs` in YAML frontmatter so they are only included after Amp reads a matching file (granular, language- or area-specific guidance).
•Run agents-md list from the command palette to see the agent files in use; Amp offers to generate an AGENTS.md if none exists.

Hooks

Supported

Lifecycle event handling via TypeScript plugins: amp.on(...) handlers can observe, approve, reject, or modify tool calls and agent turns.

Verified 2026-07-12Docs

Eventssession.startagent.starttool.calltool.resultagent.end

Config files

Path	Scope	Format	Key
`.amp/plugins/*.ts`	Project	typescript	—
`~/.config/amp/plugins/*.ts` System plugins applied across your own projects.	Global	typescript	—

Examples

Gate tool calls with a plugin

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
  amp.on('tool.call', async (event, ctx) => {
    const confirmed = await ctx.ui.confirm({
      title: `Allow ${event.tool}?`,
      message: `Amp wants to call ${event.tool}.`,
      confirmButtonText: 'Allow',
    })
    if (confirmed) return { action: 'allow' }
    return { action: 'reject-and-continue', message: `The user rejected ${event.tool}.` }
  })
}

•Amp has no shell-command hook config file; hooks are written as plugins — TypeScript files exporting a default function that receives the PluginAPI.
•tool.call handlers return allow, reject-and-continue, modify, or synthesize; agent.end handlers can return continue with a follow-up user message. There is no session.end event.
•The legacy permissions system (amp.permissions, amp.guardedFiles.allowlist, amp.dangerouslyAllowAll set to false) is now a built-in plugin activated when those settings are present.
•Plugins can also register tools (amp.registerTool), command-palette commands (amp.registerCommand), show UI, and classify with amp.ai.ask.
•Reload with `plugins: reload` from the command palette; inspect with `plugins: list`.

Commands

Deprecated

Custom slash commands (.agents/commands/) were removed in favor of skills; command-palette commands can still be added programmatically via the plugin API.

Verified 2026-07-12Docs

Invokecommand palette (Ctrl+O)

Config files

Path	Scope	Format	Key
`.agents/commands/<name>.md` Legacy location, removed. Migrate to .agents/skills/<name>/SKILL.md.	Project	markdown	—
`~/.config/amp/commands/<name>.md` Legacy location, removed. Migrate to ~/.config/agents/skills/<name>/SKILL.md.	Global	markdown	—

Examples

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
  amp.registerCommand(
    'open-plugin-docs',
    {
      title: 'Open plugin docs',
      category: 'docs',
      description: 'Open the Amp Plugin API manual page.',
    },
    async (ctx) => {
      await ctx.system.open('https://ampcode.com/manual/plugin-api')
    },
  )
}

•Custom commands in .agents/commands/ and ~/.config/amp/commands/ were two ways of doing the same thing as skills and have been removed; Amp's migration guide moves each command to a skill directory (.agents/skills/<name>/SKILL.md).
•Plugins can register command-palette actions with amp.registerCommand(...), including availability states (enabled/disabled/hidden).

Settings

Supported

JSON/JSONC settings with an amp. prefix at user, workspace, and enterprise-managed scope. Workspace settings override user settings (except keymaps).

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`~/.config/amp/settings.json` User settings (same path on macOS and Linux; %USERPROFILE%\.config\amp\settings.json on Windows).	Global	json	—
`.amp/settings.json` Workspace settings; nearest file searched upward from cwd to the repo root.	Project	json	—
`/etc/ampcode/managed-settings.json` Managed policy settings (macOS: /Library/Application Support/ampcode/managed-settings.json, Windows: %ProgramData%\ampcode\managed-settings.json).	Enterprise	json	—

Fields

Field	Type	Description
`amp.mcpServers`	object	MCP servers that expose tools (see MCP surface).
`amp.mcpPermissions`	array	Allow or reject MCP servers matching command/args or url patterns; first matching rule applies.
`amp.tools.disable`	string[]	Disable tools by name; supports glob patterns and builtin:toolname to disable only the builtin variant.
`amp.keymap`	object	Customize the CLI keymap; chords are space-separated keys. User entries override workspace entries.
`amp.skills.path`	string	Additional skill directories, colon-separated (semicolon on Windows), ~ supported.
`amp.skills.disableClaudeCodeSkills`	boolean	Disable loading skills from Claude Code directories. Default false.
`amp.notifications.enabled`	boolean	Play notification sounds when the agent completes or is blocked. Default true.
`amp.showCosts`	boolean	Show thread cost information in the CLI. Default true.
`amp.git.commit.ampThread.enabled`	boolean	Add the Amp-Thread trailer to agent commits. Default true.
`amp.git.commit.coauthor.enabled`	boolean	Add Amp as co-author in agent commits. Default true.
`amp.defaultVisibility`	object	Default thread visibility per repository origin.
`amp.remoteThreadCreation.enabled`	boolean	Let ampcode.com create new threads in this interactive TUI. Default false.
`amp.updates.mode`	string	Update checking behavior. Default auto.
`amp.fuzzy.alwaysIncludePaths`	string[]	Glob patterns always included in fuzzy file search even if gitignored.
`amp.terminal.copyOnSelect`	boolean	Copy TUI selections to the clipboard automatically. Default true.
`amp.thread.autoArchiveOnQuit`	boolean	Archive open CLI threads when quitting. Default false.

Examples

User settings

{
  "amp.mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--headless"]
    }
  },
  "amp.tools.disable": ["browser_*"],
  "amp.notifications.enabled": false
}

•Edit user settings with `amp config edit`, workspace settings with `amp config edit --workspace`; a custom file can be passed via --settings-file.
•.jsonc variants (settings.jsonc) are also read at both user and workspace scope.
•Workspace settings are found by searching upward from the cwd to the repository root.
•Enterprise managed settings override user and workspace settings and add amp.admin.compatibilityDate.
•Keymaps are the exception to precedence: amp.keymap entries in user settings override workspace entries.