Model Context Protocol (MCP)

Amplify integrates with the Model Context Protocol (MCP) : an open standard for connecting AI models to external tools and data sources. MCP servers extend Amplify's capabilities beyond the built-in native tools.

What is MCP?

The Model Context Protocol is a standardized way for AI applications to communicate with external tool providers. It defines:

Tool discovery : Servers advertise their available tools
Tool invocation : AI calls tools through a standardized protocol
Result streaming : Tool results are returned to the AI for further processing

In Amplify, MCP is managed by the MCPService singleton (app/lib/services/mcpService.ts) which:

Registers internal tools (native copilot tools, memory, context, planning)
Connects to external MCP servers via 3 transport types
Converts MCP tool definitions to AI SDK v7 ToolSet format
Merges all tools into a unified set available to the LLM

MCP and native tools

MCP tools and Amplify's native tools (read_file, create_file, etc.) are merged into the same _tools and _toolsWithoutExecute maps. The _toolNamesToServerNames map tracks which server each tool came from (server name or 'amplify' for internal). If tool names conflict, later servers override earlier ones with a warning logged.

Transport types

Amplify supports 3 MCP transport types, each validated by Zod schemas:

Internal tools registered by MCP

The MCPService registers these internal tools alongside external MCP server tools:

Native Copilot tools (via buildNativeTools()):

read_file — Read file contents from file map
list_dir — List directory contents
grep_search — Regex text search across workspace
find_files — Glob pattern file search
replace_string_in_file — Single replacement (mutation signal)
multi_replace_string_in_file — Multiple edits (mutation signal)
create_file — Create new file (mutation signal)
web_search — Web content search and fetch

Memory tools: 9. update_user_memory — Store user preferences (legacy localStorage) 10. read_user_memory — Retrieve stored memories

Context tools: 11. search_user_context — BM25 search in user profile vector store 12. store_user_fact — Store new user preference in vector store 13. search_project_context — BM25 search in project vector store 14. store_project_context — Store project context entry

Planning: 15. execute_plan — Plan execution signal for sub-chat workers

Skill tools (defined in stream-text.ts, NOT mcpService): 16. list_skills — List available skill names and descriptions 17. get_skill — Load full skill content by name 18. read_skill — Read a skill's SKILL.md 19. list_design_systems — List available design systems 20. get_design_system — Load design system content 21. inject_template — Inject starter template into workspace

MCP configuration

MCP settings are managed by the useMCPStore Zustand store:

localStorage key: mcp_settings
Default: maxLLMSteps: 5, empty mcpServers
Update flow: updateSettings() → POST /api/mcp-update-config → returns MCPServerTools
Availability check: checkServersAvailabilities() → GET /api/mcp-check

Settings UI components:

McpTab.tsx — JSON textarea config editor, max LLM steps input, example config button, save button
McpServerList.tsx — Server entries with expand/collapse, config details, status badge
McpServerListItem.tsx — Individual tool rendering with name, description, parameters
McpStatusBadge.tsx — Status indicator (available/unavailable/checking)

Example MCP configuration

A complete example showing all three transport types:

json

{
  "mcpServers": {
    "everything": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    },
    "deepwiki": {
      "type": "streamable-http",
      "url": "https://mcp.deepwiki.com/mcp"
    },
    "local-sse": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": { "Authorization": "Bearer mytoken123" }
    }
  }
}

Click the "Example Config" button in the MCP tab to populate this template.

Tool execution

MCP tools go through this execution pipeline:

AI calls a tool : The LLM selects a tool from the unified tool set
processToolCall() annotates the call with server name and description
processToolInvocations() : Sequential tool execution with:
- Approval/denial handling for mutating tools
- File mutation signal propagation for multi-step calls
- Error handling and recovery
MCP SDK communication : sdkClient.callTool() sends the request to the MCP server
Result conversion : _convertMCPToolsToToolSet() wraps the MCP response as AI SDK v7-compatible result
Stream integration : Tool results are merged into the SSE stream for the client

Sequential execution

Tool calls are executed sequentially (not in parallel). This ensures mutation signals from one tool are applied before the next tool runs, preventing conflicts when multiple tools modify the same file.

Built-in skills

Skills are another extensibility mechanism alongside MCP.

API reference

MCP API endpoints for configuration and availability checks.

Was this page helpful?

View on GitHub