{"title":"Documentation MCP server","description":"Connect an MCP client to Amber's live, read-only V2 documentation tools","section":"guides","version":"v2","path":"guides/ai-assistants/mcp","canonical_url":"https://amberframework.org/docs/v2/guides/ai-assistants/mcp","markdown_url":"https://amberframework.org/docs/v2/guides/ai-assistants/mcp.md","inherited":false,"content_markdown":"# Documentation MCP server\n\nAmber publishes a remote, read-only Model Context Protocol endpoint at:\n\n```text\nhttps://amberframework.org/mcp\n```\n\nThe server exposes three tools:\n\n| Tool | Use it for |\n|---|---|\n| `search_docs` | Find V2 pages by task, concept, API, or filename. |\n| `read_doc` | Read one canonical page as Markdown. |\n| `list_docs` | List the complete published V2 documentation set. |\n\nThe endpoint never writes to an Amber application, repository, account, or\ndeployment. Tool results point back to canonical public pages so an assistant\ncan cite the source it used.\n\n## Where the examples go\n\n- The JSON object is MCP client configuration. Add it in the client's server\n  settings; do not create it inside an Amber application.\n- The `curl` examples run in any terminal and only verify the public endpoint.\n  They do not create or modify an application file.\n- This guide creates no application source. Do not add the examples to\n  `src/`, `config/`, `public/`, `spec/`, or `shard.yml`.\n\n## Add it to an MCP client\n\n**Client configuration — add this as a remote HTTP MCP server, not as an Amber\napplication file.**\n\n```json\n{\n  \"mcpServers\": {\n    \"amber-docs\": {\n      \"url\": \"https://amberframework.org/mcp\"\n    }\n  }\n}\n```\n\nMCP clients use different settings screens and configuration filenames. Keep\nthe server name and URL above, then follow the client's instructions for adding\na remote HTTP server. No Amber API key or authorization header is required.\n\n## Verify the endpoint directly\n\n**Run from: any terminal; this command does not belong in an Amber project.**\n\n```bash\ncurl https://amberframework.org/mcp \\\n  --header 'Content-Type: application/json' \\\n  --header 'Mcp-Method: tools/list' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\nA successful response has `jsonrpc: \"2.0\"`, the same `id`, and a `result.tools`\narray containing `search_docs`, `read_doc`, and `list_docs`.\n\n## Call a documentation tool\n\n**Run from: any terminal.**\n\n```bash\ncurl https://amberframework.org/mcp \\\n  --header 'Content-Type: application/json' \\\n  --header 'Mcp-Method: tools/call' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"search_docs\",\"arguments\":{\"query\":\"background job work stealing\"}}}'\n```\n\nFor a specific page, call `read_doc` with a documentation-relative path such\nas `guides/websockets` or `/docs/v2/guides/background-jobs`.\n\n## Protocol boundary\n\nThe endpoint supports the current stateless `2026-07-28` discovery and tool\nmethods. It also accepts the legacy `initialize` and\n`notifications/initialized` handshake used by 2025 MCP clients. Current clients\ncan call `server/discover`, `tools/list`, and `tools/call` without creating a\nsession. The optional `Mcp-Method` request header must match the JSON-RPC method\nwhen supplied.\n\nBecause the tool set and public documentation are cacheable, list and discovery\nresponses include a 15-minute public cache lifetime. Tool calls themselves are\nreturned with `Cache-Control: no-store` at the HTTP layer.\n\n## Use the other machine-readable formats\n\nMCP is the searchable assistant interface. These simpler public formats remain\nuseful for scripts and readers:\n\n- add `.md` to a main site, documentation, or blog URL for its Markdown representation;\n- add `.json` for structured page, guide, or post data;\n- use `/docs/v2/PAGE_PATH.md` for a documentation page's exact Markdown source;\n- use `/docs/v2/knowledge.md` for the complete V2 knowledge bundle;\n- use `/llms.txt` for the machine-oriented site map;\n- use `/blog/feed.xml` or `/rss` for the chronological publication feed.\n\nHTML remains the human browsing representation. JSON is structured data,\nMarkdown is the readable source representation, RSS is the subscription stream,\nand MCP provides discovery plus targeted retrieval. They are complementary,\nnot aliases for the same job."}