5841cc57b7
## Summary Anthropic's [connector review criteria](https://claude.com/docs/connectors/building/review-criteria) and [submission requirements](https://claude.com/docs/connectors/building/submission) call out two things our `/mcp` endpoint is missing today: - every tool needs a `title` plus `readOnlyHint` / `destructiveHint` annotation - a public docs page covering setup and usage must exist by publish date This PR adds both: - **Tool annotations** on all 7 MCP tools (`compile`, `list_compilers`, `list_languages`, `list_libraries`, `lookup_asm_instruction`, `generate_short_url`, `get_shortlink_info`). All read-only tools get `readOnlyHint: true`. `generate_short_url` is marked `readOnlyHint: false` + `destructiveHint: false` + `idempotentHint: true` (it's additive and the storage layer dedupes by config hash). Every tool gets `openWorldHint: false` since none reach out to third-party services. - **`docs/MCP.md`** describing the endpoint URL, transport, tool catalogue, and a Claude Code setup line. A judgement call worth flagging: `compile` is annotated `readOnlyHint: true` even though `execute=true` runs user code. The CE service is stateless from the connector's point of view and sandbox effects don't escape the call, so the hint matches the spirit of the annotation, but we may want to revisit if Anthropic pushes back during review. Two known gaps not addressed here, that I'd like to discuss separately before submission: - **Origin-header validation** — required by the submission doc as DNS-rebinding mitigation. The threat model mostly applies to localhost-bound desktop servers; we're a public HTTPS service with no auth, so the public REST API's `Allow-Origin: *` posture is consistent. Suggest asking Anthropic to confirm exemption, or add an allowlist with a missing-Origin pass-through (Claude Code currently sends none). - **Submission form prep** — name/tagline/description/screenshots/logo, and a pass through MCP Inspector. Operational, not code. ## Test plan - [x] `npm run ts-check` - [x] `npm run lint` - [x] `npm run test -- --run mcp` (78 tests pass) - [x] pre-commit hook runs clean - [ ] manual smoke test from a fresh Claude Code MCP install (`claude mcp add --transport http compiler-explorer https://godbolt.org/mcp` once deployed) - [ ] confirm tool annotations show up correctly in MCP Inspector 🤖 Generated with [Claude Code](https://claude.com/claude-code)
4.0 KiB
MCP endpoint
Compiler Explorer ships a built-in Model Context Protocol server that lets LLM clients drive CE the same way the web UI does: list languages and compilers, compile (and optionally execute) source, look up assembly instruction docs, and round-trip short URLs.
The endpoint is unauthenticated and lives alongside the public REST API on every CE deployment.
Connection details
- URL:
https://godbolt.org/mcp(or<your-ce-host>/mcpfor self-hosted). - Transport: Streamable HTTP, stateless (one JSON-RPC POST per call, no session id).
- Methods accepted:
POSTfor tool calls;OPTIONSfor CORS preflight.GETandDELETEreturn405 Method Not Allowed. - Auth: none.
Using it from a Claude client
In Claude Desktop or Claude Code, add a custom HTTP MCP server pointing at
https://godbolt.org/mcp. No credentials required.
For Claude Code on the command line:
claude mcp add --transport http compiler-explorer https://godbolt.org/mcp
Tools
Successful responses are JSON in a single text content block. Error responses set
isError: true and put a plain-text human-readable message in the same block (not
a JSON envelope) — e.g. Short link "abc" not found, Compilation error: ....
list_languages
Returns every supported language, with its default compiler id and the number of compilers that target it. Read-only.
list_compilers
List compilers, optionally filtered by language, instructionSet, or a free-text
match. The latestPerMajor flag reduces the firehose to "newest stable per
(language, arch, semver major), all nightly + prerelease, no experimentals" — the
right default when an LLM is picking a compiler. lean: true drops everything but
id and name. Read-only.
list_libraries
List libraries available for a given language, with the same match/maxResults/lean
controls as list_compilers. Read-only.
compile
Compile a source string with a chosen compiler and options, optionally linking
libraries and optionally executing the result. With execute: true the program
runs in CE's ephemeral sandbox; runtime output appears at the top level and the
compile diagnostics move to buildResult. Output is line-capped (defaults: 500 asm,
100 stdout, 100 stderr) — raise the maxAsmLines / maxStdoutLines / maxStderrLines
caps to retrieve more. Read-only from the connector's point of view; sandbox effects
do not escape the call.
lookup_asm_instruction
Retrieve documentation for an assembly mnemonic in a given instruction set
(amd64, arm64, riscv, …). Read-only.
generate_short_url
Persist a Compiler Explorer short URL that captures source, language, compiler, options,
and libraries, and return its https://godbolt.org/z/... form. Additive only — repeat
calls with the same payload return the same URL (the storage layer dedupes by config
hash). Marked as a write tool with idempotentHint: true.
get_shortlink_info
Resolve an https://godbolt.org/z/<id> URL (or just the id) back into source plus
compiler config. The returned compiler entries use the same shape compile accepts
({compiler, options, libraries:[{id, version}]}), so a shortlink can be re-compiled
without translation. Multi-pane shortlinks (executors, conformance views, CMake trees)
are flattened to the basic compile inputs. Read-only.
Notes for tool authors
- All tools carry MCP
annotations(title,readOnlyHint/destructiveHint,openWorldHint: false); seelib/mcp/tools/*.ts. - The server uses
StreamableHTTPServerTransportin stateless mode (sessionIdGenerator: undefined). Each POST is a complete request/response cycle. - Tool implementations live in
lib/mcp/tools/and are wired up inlib/mcp/index.ts. Tests live intest/mcp/.
Reporting issues
File MCP-specific bugs at https://github.com/compiler-explorer/compiler-explorer/issues.