> ## Documentation Index
> Fetch the complete guide index at: https://www.synscribe.com/agentic-discovery/llms.txt
> Use this file to discover all pages before exploring further.

---
title: "Publish an MCP Server So Agents Actually Find It"
description: "How to publish an MCP server and get it found: registry publish in ~1 hour, .well-known/mcp.json, sandbox endpoints, and install snippets for 8+ clients."
slug: /agentic-discovery/mcp-server-distribution
series: "The Agentic Discovery Playbook — Play 3 of 11 · GET FOUND"
last_verified: 2026-06-11
---

# Publish and Distribute an MCP Server (So Agents Actually Find It)

> **In short:** To publish an MCP server agents find: ship a remote docs-MCP first, add a live server with a separate sandbox endpoint, publish to the Official MCP Registry via `mcp-publisher` (~1 hour — it propagates into VS Code), serve `/.well-known/mcp.json`, and put copy-paste install snippets for 8+ clients in your docs. The server is the easy half; distribution decides selection.

## Do this now

- [ ] Ship a **remote** docs-MCP at `mcp.{yourdomain}` exposing `search_{product}_documentation` — no auth, no local install.
- [ ] Add a sandbox variant as a **separate URL** (Polar pattern), not a flag buried in config.
- [ ] Gate destructive production capability behind an explicit opt-in flag (Convex pattern); default-deny.
- [ ] Publish to the Official MCP Registry with `mcp-publisher`; verify your entry renders in VS Code under `@mcp`.
- [ ] Serve `https://{yourdomain}/.well-known/mcp.json` — as of 2026-06-11, Resend is the only product doing this in the wild.
- [ ] Add per-client install snippets for 8+ clients to your docs, including a literal `config.toml` block for Codex.
- [ ] Put an "Add to Cursor" deeplink button on your docs and README.
- [ ] Publish a security page (prompt-injection guidance, read-only mode, key scoping) and stand up the integration-completion eval in CI.

## Who needs this play?

Any product whose integration an agent might write: APIs, infrastructure, dev tools, platforms with operational surface. A docs-MCP applies to anyone with a documentation corpus; the live-system server applies once agents can usefully *operate* your product, not just read about it.

Budget honestly: docs-MCP 1–2 weeks, live MCP plus sandbox 2–6 weeks, the discovery layer 2–3 days. This page covers the build-and-distribute mechanics; the broader registry strategy (which directories matter at all) is [Play 2](/agentic-discovery/ai-agent-registries-and-directories), and the skills layer that often ships alongside is [Play 4](/agentic-discovery/agent-skills-and-agents-md).

## What should you ship first — a docs-MCP or a live MCP?

Docs first. The demand evidence, as of 2026-06-11: Context7 — a pure docs-retrieval MCP — is the largest measured docs-MCP install base at **1,136,447 npm downloads per week** (~56.5K GitHub stars), with no major client bundling it by default. Developers voluntarily install docs retrieval at scale; a vendor docs-MCP rides the same demand for your own corpus.

The docs-MCP spec:

1. Build a **remote** streamable-HTTP server at `mcp.{domain}` or `{domain}/docs/mcp`. Remote-first means zero install friction, you control updates, and you get usage telemetry.
2. Core tool: `search_{product}_documentation(query)` returning ranked snippets with code, imports, and source URLs — mirror Stripe's `search_stripe_documentation` naming.
3. Optional advanced tool, Bun pattern: a sandboxed **read-only filesystem view over your docs** supporting `rg`/`tree`/`cat` (Bun ships `search_bun` + `query_docs_filesystem_bun` at bun.com/docs/mcp). Agents get to grep docs the way they grep code.
4. Make every snippet self-contained: install command + imports + a minimal runnable example. The same rubric drives your Context7 score, so the corpus does double duty.
5. **No auth on the docs-MCP.** Friction here is pure loss.

## How do you ship a live MCP without scaring users (or yourself)?

Start read-only: status, list/get resources, logs, schema introspection. Convex's deployment server is the reference shape — `npx -y convex@latest mcp start` exposes status, tables, data, runOneoffQuery, functionSpec, and logs.

Then add the safety architecture the field has converged on:

- **Sandbox as a separate server URL**, not a config flag. Polar runs `mcp.polar.sh/mcp/polar-mcp` (production) and `mcp.polar.sh/mcp/polar-sandbox`. Docs and agents can then say "use sandbox" unambiguously, and demos and CI evals never touch production.
- **Destructive production capability behind a deliberately scary flag.** Convex's is `--dangerously-enable-production-deployments`. Default-deny.
- **Scoping parameters on the hosted URL**, Supabase pattern: `read_only=true`, `project_ref=...`, `features=...` — users pin the blast radius at install time.
- **OAuth for the remote server, restricted scoped keys as fallback** (Stripe supports both).

Tool design rules: name tools `search_{product}` / `get_{product}_{noun}` / `create_{product}_{noun}` — the product name disambiguates in multi-server sessions and brands every tool call in transcripts. Keep the count tight (Stripe covers its whole API in ~25 tools; every extra tool costs context tokens in every session). Write descriptions as model-facing retrieval keys: what the tool does, when to prefer it, input constraints, an example call. And include the docs-search tool inside the live server too, so one install covers retrieval and action.

## How do you publish to the Official MCP Registry?

This is the highest-leverage hour of the whole play. The Official MCP Registry (repo at 6.9k stars, v1.7.9 May 2026) feeds named consumers — Smithery, PulseMCP, Docker Hub, Anthropic, GitHub — and the GitHub MCP Registry it feeds is rendered **natively in VS Code's Extensions view** (`@mcp`), the only registry surfaced by default inside a major client.

The `mcp-publisher` walkthrough:

1. Write `server.json`: name, description, package or remote endpoint, version.
2. Choose a namespace: `io.github.<org>/<server>` (verified via GitHub OIDC) or reverse-DNS `com.<yourdomain>/<server>` (DNS TXT or HTTP challenge).
3. `mcp-publisher login github` (or run the DNS flow).
4. `mcp-publisher publish`.
5. Verify the entry appears in the GitHub MCP Registry, then search `@mcp <product>` in VS Code.
6. Re-run `mcp-publisher publish` on **every version bump** so downstream consumers carry current metadata.

One caveat that costs teams the entire Claude surface: Claude Code's `/mcp` does **not** browse this registry. Anthropic's Connectors Directory and plugin marketplace are separate, parallel submissions — [Play 2](/agentic-discovery/ai-agent-registries-and-directories) has the runbook.

## What is .well-known/mcp.json and should you serve it?

A machine-readable discovery manifest at a standard path, so an agent that knows your domain can find your server without a registry. Serve two:

- `https://{domain}/.well-known/mcp.json` — server URLs, transport, auth method, docs link.
- `https://{domain}/.well-known/agent-skills/index.json` — if you ship skills ([Play 4](/agentic-discovery/agent-skills-and-agents-md)).

As of 2026-06-11, **Resend is the only product we found doing this in the wild** (`resend.com/.well-known/mcp.json` plus the agent-skills index). That's the argument: it costs an afternoon, and there is near-zero competition for a surface agents can resolve deterministically from your domain name.

## Which install snippets do your docs need?

Per-client snippets for at least the 8 clients Polar covers — Cursor, Windsurf, Codex, Claude Code, OpenCode, ChatGPT, Claude Desktop, VS Code (Vercel covers 12). Agents read these docs pages and execute the snippets verbatim, so every snippet must be copy-paste complete: an unexplained placeholder becomes a failed install.

```jsonc
// Cursor / Claude Desktop / VS Code
// (.cursor/mcp.json, claude_desktop_config.json, .vscode/mcp.json)
{ "mcpServers": { "{product}": { "url": "https://mcp.{domain}/mcp" } } }
```

```toml
# Codex (~/.codex/config.toml) — the ONLY route to Codex users; no registry exists
[mcp_servers.{product}]
url = "https://mcp.{domain}/mcp"
```

```bash
# Claude Code
claude mcp add --transport http {product} https://mcp.{domain}/mcp
# Generic one-liner (Vercel pattern)
npx add-mcp https://mcp.{domain}/mcp
```

Add the one-click paths on top: a Cursor **"Add to Cursor" deeplink + badge** on docs and README (cursor.com/docs/context/mcp/install-links — works with no directory listing), the `npx add-mcp` one-liner (Vercel pattern), or your own CLI installer like Better Auth's `npx auth@latest mcp --cursor|--claude-code`.

The Codex line bears repeating: there is no Codex registry at all — discovery is an open feature request (openai/codex#25750). If your docs lack a `config.toml` block, Codex users have no route to you.

## What security documentation do reviewers and agents expect?

A dedicated security section is now table stakes, and it doubles as a selection asset — agents and human reviewers both read it. Cover:

- **Prompt-injection risk** when tools return untrusted data (Supabase publishes exactly this guidance; Vercel ships security guidance with its 12-client setup docs).
- The recommendation to use **read-only/sandbox modes** for agent sessions.
- **Key scoping** — what each tool can and cannot mutate.
- The **production-gating flag** and why it exists.

This is not optional polish. An ungated live server whose default config can mutate production is one prompt injection away from an incident, and it will fail Anthropic's Connectors-style review (which already takes days–weeks — don't add a rejection cycle).

## How do you prove agents can complete an integration?

Run the eval suite in CI against the **sandbox** endpoint:

1. **Protocol conformance** — initialize a session, list tools, assert expected tool names and JSON-schema-valid definitions. FAIL on drift.
2. **Docs-search quality** — a golden set of ≥25 real integration questions; the top-3 returned snippets must contain the known-correct API symbol or code for ≥90%.
3. **Integration-completion (the core metric)** — in a clean container, a pinned agent + model gets golden tasks ("integrate {product} checkout into this starter," "send a templated email") with only the MCP server configured. PASS = the generated project builds and an end-to-end smoke test passes against sandbox. Track completion rate, tool-call count, and tokens per task; alert on regression >10%. Run ≥3 trials per task — sampling variance is real at small n.
4. **Safety** — with default config, an instructed destructive production action must be refused; `read_only=true` must block all write tools.
5. **Discovery checks** — HTTP 200 + schema-valid JSON for `/.well-known/mcp.json`; registry API returns the current version; the Cursor deeplink decodes to valid config; every documented install snippet passes a JSON/TOML lint.
6. **Auth flows** — OAuth completes headlessly against sandbox; a narrowly scoped key can call read tools and is rejected on writes.

Why this is the metric that matters: in our pilot trials (single model, n=2 per arm, 2026-06-11), telling an agent that one email provider ships MCP + llms.txt + skills flipped its provider selection 2/2 (experiment E4; control 2/2 chose the other provider). Agent-operability is becoming a selection criterion — pilot-grade evidence, but it points one direction: the agents that can *finish* the integration recommend the product they finished it with.

## What happens if you build the server but skip distribution?

**Crossmint is the counterexample.** It ships a full agent surface — a docs MCP at docs.crossmint.com/mcp, llms.txt, agent-facing commerce APIs — yet has **no findable Context7 entry** as of 2026-06-11. Full build cost, near-zero presence where agents actually retrieve. Phases 1–3 without Phase 4 produce an invisible server.

The adjacent failure is outsourcing distribution to standalone directories. Smithery lists 10,576+ MCP servers, but visible usage is tiny — Exa at 23.2K uses, Context7 at 6.8K there versus its 1.14M weekly npm downloads. Directories are checkboxes, not channels; your docs, the official registry chain into VS Code, and one-click installs are the channels.

And one strategic counterexample: Hono ships no docs-MCP and positions as MCP *infrastructure* (`@hono/mcp` middleware). Measurable cost: its repo-sourced Context7 entry has 48 snippets, benchmark 63.3, absent from the top-50. A valid strategy only if you sell to MCP builders rather than through agents.

## The receipts

All figures verified 2026-06-11; methodology and updates in the [Data Room](/agentic-discovery/data). The field has converged on the pattern this play prescribes:

| Product | Server architecture | Distribution moves |
|---|---|---|
| Stripe | Remote `mcp.stripe.com`; OAuth or restricted keys; ~25 tools incl. `search_stripe_documentation` | Per-client snippets; agent docs at `/agents.md` and `/building-with-ai.md` |
| Polar | Production + sandbox as **separate remote servers** (`/mcp/polar-mcp`, `/mcp/polar-sandbox`) | Install recipes for 8 clients |
| Vercel | Remote OAuth `mcp.vercel.com` | `npx add-mcp` one-liner; setup docs for 12 clients; security guidance |
| Supabase | Hosted `mcp.supabase.com/mcp` with `read_only`/`project_ref`/`features` params | Prompt-injection security guidance |
| Convex | Live deployment tools; prod behind `--dangerously-enable-production-deployments` | Cursor one-click deeplink badge |
| Better Auth | Remote docs-MCP `mcp.better-auth.com/mcp` | Own-CLI installer `npx auth@latest mcp`; MCP-auth plugins became product surface |
| Bun | `search_bun` + `query_docs_filesystem_bun` (read-only shell over docs) | Resource `mintlify://skills/bun` |
| Resend | github.com/resend/resend-mcp | `.well-known/mcp.json` + `.well-known/agent-skills/index.json` — the only well-known agent discovery found in the wild |
| DodoPayments | MCP shipped April 2025 (changelog v1.13.0); "Code Mode" MCP | Agent Plugin: "MCP servers and skills in one install" for Claude Code/Codex/Cursor/OpenCode |

**Demand evidence:** `@upstash/context7-mcp` at 1,136,447 npm downloads/week is the measured ceiling for voluntary docs-MCP adoption — no client bundles it by default.

**Bypass evidence:** Context7 shows 6.8K uses on Smithery against 1.14M/week on npm — roughly 99% of distribution flows around standalone directories, through npm, native client surfaces, and vendors' own docs.

**Selection evidence (pilot-grade):** E4, single model (Haiku 4.5), n=2 per arm — announcing an MCP + llms.txt + skills surface flipped provider choice 2/2 vs 2/2 control. We state the scale because the honesty is the point; the replication slot is open.

**Absence evidence:** Crossmint (full surface, no registry presence) and Codex (no registry exists; openai/codex#25750) — the two reminders that distribution is never automatic.

## FAQ

**How do I publish an MCP server to the official registry?**
Write a `server.json`, verify your namespace, and run `mcp-publisher publish` — about an hour, free. Use `io.github.<org>/<server>` with GitHub OIDC, or `com.<domain>/<server>` with a DNS TXT/HTTP challenge. The entry propagates to the GitHub MCP Registry and VS Code's `@mcp` view; re-publish on every release.

**Should my MCP server require authentication?**
The docs-MCP should require none — friction there is pure loss. The live-system server should support OAuth for the remote endpoint with restricted, scoped API keys as a fallback (Stripe supports both), plus install-time scoping parameters like Supabase's `read_only` and `project_ref`.

**How do AI agents discover MCP servers?**
Through native client surfaces (VS Code renders the GitHub MCP Registry in its Extensions view), install snippets in your own docs that agents execute verbatim, and machine-readable manifests at `/.well-known/mcp.json`. Standalone directories carry little traffic — Context7 shows 6.8K Smithery uses against 1.14M weekly npm downloads.

**Do I need a sandbox version of my MCP server?**
Yes — as a separate endpoint, not a buried flag. Polar runs production and sandbox as distinct URLs, which lets docs say "use sandbox" unambiguously, keeps demos away from production data, and gives your own integration-completion evals a safe target in CI.

**How do I get my MCP server into Cursor and Codex?**
For Cursor, publish "Add to Cursor" deeplinks on your docs — they work without any directory listing, and the in-product directory appears curated with no verified self-serve path. For Codex there is no registry at all (open feature request openai/codex#25750): a literal `config.toml` snippet in your docs is the only route.

---

*Last verified 2026-06-11. We re-test the claims on this page quarterly — changes are logged in the [Data Room](/agentic-discovery/data).*

**Part of [The Complete Playbook to Agentic Discovery](/agentic-discovery).**

← Previous: [AI Agent Registries & Directories](/agentic-discovery/ai-agent-registries-and-directories) · Next: [Agent Skills & AGENTS.md](/agentic-discovery/agent-skills-and-agents-md) →

> **Stay ahead of the agents.** We re-test this playbook quarterly and publish what changed — new data, busted myths, ranking shifts. [Get the update digest →](/agentic-discovery#updates)
>
> **Want this done for you?** Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. [Talk to us →](/contact)