adding-mcp-store-servers

Adding a server to the MCP store

The MCP store catalog is code: one entry in products/mcp_store/backend/catalog.py per server. On deploy, sync_mcp_server_templates upserts entries into MCPServerTemplate rows in every environment — there are no data migrations, no icon assets, and no manual admin steps for most servers. Adding a server is a small PR to that file.

Read first

• products/mcp_store/README.md — the catalog pipeline, sync semantics, and operator runbook
• products/mcp_store/backend/catalog.py — existing entries; match their tone and shape
• products/mcp_store/backend/probe.py — what the probe verifies and what passed_activation_gate means

Workflow

1. Find the vendor's remote MCP endpoint. Check the vendor's docs (search " MCP server"); most publish a hosted endpoint like https://mcp.<vendor>.com/mcp. Only hosted (remote) MCP servers belong in the catalog — local/stdio servers do not. Cross-check public MCP registries if the docs are unclear.

2. Probe it.

   DEBUG=1 python manage.py probe_mcp_server https://mcp.example.com/mcp
   

   The JSON verdict tells you everything the entry needs:

   • speaks_mcp: false → the probe could not verify MCP. Stop and re-research — with one exception: reachable: true plus the error "Initialize was rejected and no OAuth metadata was discovered" is the auth-walled API-key case (last bullet below).
   • auth_flavor: "oauth_dcr" with passed_activation_gate: true → OAuth with Dynamic Client Registration. The entry is auth_type="oauth" and will activate automatically on merge.
   • auth_flavor: "oauth_shared" → OAuth without DCR. The entry is auth_type="oauth" but normally ships inactive; an operator must register an OAuth app with the vendor and paste credentials in Django admin (see the operator checklist below — include it in your PR description). If PostHog already provisions that exact OAuth app through an instance credential source, declare the reviewed source instead; catalog sync verifies and activates it without copying secrets.
   • auth_flavor: "open" → the handshake completed without credentials. auth_type="api_key"; activates automatically on merge.
   • auth_flavor: "api_key_or_unknown" with reachable: true → an auth-walled API-key server; a bare 401/403 gives the probe no MCP evidence. auth_type="api_key", but the entry ships inactive — verify it with a real install (Gate B) before adding it, and note in the PR that an operator flips it active in Django admin per environment (users bring their own key; nothing to provision).

3. Author the entry in catalog.py, alphabetically by name:

   • name — the vendor's own casing ("PagerDuty", not "Pagerduty").
   • description — one sentence, sentence case, verb-first, matching the existing entries ("Manage Linear issues, projects, and team workflows."). No marketing copy.
   • category — the closest of business / data / design / dev / infra / productivity.
   • icon_domain — the vendor's primary brand domain (linear.app, not mcp.linear.app). Verify logo.dev has it: GET /api/projects/@current/hog_functions/icons/?query=<vendor> from a dev session, or check https://img.logo.dev/<domain> renders a real logo.
   • docs_url — the vendor's MCP docs page when they have one.

4. Verify end-to-end when you can (Gate B). The probe covers everything up to the OAuth consent screen. If you have an account with the vendor, complete one real install in local dev: run the stack, install the server from the store UI, finish the OAuth flow (or paste an API key), and confirm the tool list populates. Record the verification tier in the PR description:

   • Tier 1: probe passed + real install verified (tools listed).
   • Tier 2: probe passed only (no vendor account available).

5. Run the checks.

   hogli test products/mcp_store/backend/test/test_catalog_sync.py
   

   test_catalog_entries_are_valid catches malformed entries (bad category, duplicate URL, unnormalized icon_domain) before they hit production.

6. Open the PR — one server per PR, on an mcp-store/-prefixed branch (e.g. mcp-store/add-pagerduty), with a feat(mcp-store) title: feat(mcp-store): add <name> to the MCP server catalog. State the probe verdict and verification tier in the description. For oauth_shared servers without an existing instance credential source, include the operator checklist so activation isn't forgotten.

Operator checklist for oauth_shared servers (paste into the PR)

This server does not support Dynamic Client Registration, so it ships inactive. To activate (per environment, US and EU):

- [ ] Register an OAuth app in the vendor's developer console
- [ ] Redirect URI: `https://us.posthog.com/api/mcp_store/oauth_redirect/` (and the EU equivalent)
- [ ] Paste client ID + secret into Django admin → MCP server templates → <name>
- [ ] OAuth metadata was auto-discovered by the sync; run the "Discover metadata" admin action only if it's empty
- [ ] Tick "is active"

What not to do

• Don't add entries with unprobed URLs — a dead catalog entry is user-visible breakage.
• Don't edit is_active, oauth_credentials, or oauth_metadata expectations into the catalog — those are operational state owned by the row, not by code.
• Don't add an instance credential source for a newly registered vendor app. Sources are only for an existing client already provisioned across every target environment, with exact trusted issuer, authorization, and token endpoints enforced before any secret is used.
• Don't add icon assets or icon_key values — icons resolve from icon_domain via logo.dev at render time.
• Don't batch unrelated servers into one PR unless explicitly doing a scaffold sweep; per-server PRs keep review and reverts clean.