Skip to content
Murmur Atlas · Internal

RFC-0001: murmur-docs-mcp

Summary

Section titled “Summary”

A small MCP server, murmur-docs-mcp, exposing Atlas’s content as typed tools (search_docs, get_doc, get_service, …) so Claude Code, Cursor, and other MCP clients can retrieve authoritative Murmur architecture instead of re-deriving it from source on every session.

Motivation

Section titled “Motivation”

Today, an agent working in murmur-app or murmur-web has to rediscover service topology, ownership, and runbook procedures from source comments and READMEs every session — slow, and prone to missing context that lives only in Atlas (or nowhere). A docs MCP server turns Atlas into queryable infrastructure, not just a website.

Goals

Section titled “Goals”
  • Read-only tools over PUBLIC and (separately, access-gated) INTERNAL content.
  • No new database — reads Atlas’s own built output (or content collection at build time), same source of truth as the site.

Non-Goals

Section titled “Non-Goals”
  • Write access (editing docs via MCP) — out of scope for v1.
  • Replacing /llms.txt and the .md endpoints for simple agent access — MCP is for agents that specifically want structured, typed queries.

Proposal

Section titled “Proposal”

All 8 tools are implemented and tested — search_docs, get_doc, get_service, get_runbook, get_architecture, get_parameter, get_api_endpoint, get_related_docs. See mcp/murmur-docs-mcp/README.md in the murmur-docs repo for the full tool table and the “Why local-first for internal tools” section, which departs from this RFC’s original framing in one way worth calling out here: the internal-scoped tools default to reading content/docs/internal/** directly off local disk (the same pattern get_doc already used for public content) rather than requiring network/Access auth unconditionally — running the server at all implies repo access, which is the same boundary Access enforces for a human. The Service Token auth path from the Security section below is implemented as a fallback for running without a local checkout, not the only way in.

Architecture

Section titled “Architecture”

murmur-docs-mcp runs as a small Node process implementing the MCP stdio transport, reading Markdown files directly off disk (or, eventually, over HTTP from the deployed .md endpoints) rather than depending on a running Astro server.

API Changes

Section titled “API Changes”

N/A (new server, not a change to an existing one).

Security

Section titled “Security”

Resolved (was an open question — see update below): Cloudflare Access Service Tokens. The internal tool set (get_service, get_runbook, internal-scoped search_docs) authenticates to atlas.murmurmusic.ai the same way any headless/automated client does behind Access — a static Client ID + Client Secret pair, sent as CF-Access-Client-Id / CF-Access-Client-Secret request headers, exchanged by Cloudflare for a JWT before the request reaches the origin. This is Cloudflare’s own documented mechanism for exactly this case (“Authenticate coding agents,” Cloudflare One docs) — not a homegrown auth scheme layered on top of Access, which is the thing to avoid per this RFC’s original framing (“an MCP server is a second door into the same house and needs the same lock”).

Concretely:

  1. Add a Service Auth policy to the atlas.murmurmusic.ai Access application (alongside the human email-domain policy from cloudflare-access.md), scoped to the service token created for murmur-docs-mcp.
  2. Generate the token in Zero Trust → Access → Service Auth → Service Tokens. The secret is shown once — store it the same way the existing CLOUDFLARE_API_TOKEN is stored (~/.config/murmur/cloudflare.env pattern), never in this repo.
  3. murmur-docs-mcp reads CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET from the environment and attaches them as headers when fetching internal .md endpoints. Never logged, never committed — same rule as scripts/cloudflare-setup.mjs’s token handling.

Longer-term alternative, worth revisiting once this is live: Cloudflare also ships MCP server portals (Access → AI Controls), which front an MCP server with Access directly and let other agents (not just this one) authenticate via OAuth or a service token through Cloudflare’s own portal, without murmur-docs-mcp handling credentials itself at all. More setup, but removes the credential-handling code above entirely if multiple agents/teams end up needing internal access. Noted here rather than chosen now — v1 is one team’s Claude Code sessions, which doesn’t yet need portal-level multi-agent management.

Operations

Section titled “Operations”

v1 PoC is local-only (a developer runs it against their checkout). A hosted version behind the Service Auth policy above is the next step, not yet built.

Migration

Section titled “Migration”

N/A — net new.

Alternatives

Section titled “Alternatives”
  • Skip MCP, rely on /llms.txt + .md endpoints only — considered sufficient for simple retrieval, but doesn’t give an agent typed, parameterized queries (get_parameter(product, id)) the way a real tool call does.

Open Questions

Section titled “Open Questions”
  • How does murmur-docs-mcp authenticate for internal-scoped tools without reimplementing Cloudflare Access’s job? Resolved — see Security above (Access Service Tokens).
  • Should it proxy the live deployed site, or read the content collection directly (faster, but requires the MCP server and the site to deploy from the same commit to avoid drift)? Still open.