archestra-mcp-catalog-entry

name	archestra-mcp-catalog-entry
description	Use when adding a new MCP server to the public MCP catalog (mcp-catalog/data) or preparing/reviewing a catalog-entry PR. Derives the entry name from the server URL, live-probes remote servers to fill in tools/transport/auth, fetches and encodes the icon, and validates the manifest against the catalog schema before opening the PR.

Add an MCP server to the Archestra MCP Catalog

The catalog is two files under mcp-catalog/data/ (see mcp-catalog/README.md):

• mcp-servers.json — the master URL list. An entry only appears in the catalog if its URL is here.
• mcp-evaluations/<name>.json — one manifest per server.

Entries are maintained by hand — there is no scraping/evaluation pipeline. Your job is to machine-fill everything that CAN be derived (name, tools, transport, icon, defaults) so the human only supplies judgment calls (description quality, category, keywords).

1. Derive the entry name from the URL (do not guess)

The website derives the name from the URL; the filename and the manifest's name field must match it exactly:

• GitHub https://github.com/<owner>/<repo> → <owner>__<repo> (lowercased). Monorepo path …/tree/<branch>/<p1>/<p2> → <owner>__<repo>__<p1>__<p2>.
• Remote endpoint → take the hostname, strip a leading www./mcp./api. (only those three), take everything before the first remaining dot, append __remote-mcp.
  • https://mcp.linear.app/mcp → linear__remote-mcp
  • https://agenttools.wolfram.com/mcp → agenttools__remote-mcp (NOT wolfram__remote-mcp — only www./mcp./api. are stripped)

2. Live-probe remote servers (machine-fill, don't transcribe docs)

For server.type: "remote", verify the endpoint and extract facts directly:

# initialize — confirms the endpoint is live, speaks streamable HTTP, and whether auth is required
curl -sS -m 20 -X POST <url> -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"archestra-catalog","version":"1.0"}}}' -D -

• HTTP 200 with a result → no auth required (archestra_config.oauth.required: false, no oauth_config).
• HTTP 401/403 (often with WWW-Authenticate / resource metadata) → OAuth required; copy the oauth_config shape from an existing OAuth entry (e.g. jam__remote-mcp.json).
• Then call tools/list (reuse the Mcp-Session-Id response header if one was returned) and fill the manifest's tools array with the REAL tool names + descriptions, not the vendor docs.

3. Write the manifest

Copy a fresh entry as the template — mcp-catalog/data/mcp-evaluations/excalidraw__remote-mcp.json (remote, no auth) or jam__remote-mcp.json (remote, OAuth). Current field set:

{
  "name": "<derived name>",              // must equal the filename
  "display_name": "<Human Name>",
  "description": "<1-3 factual sentences — trim vendor marketing speak>",
  "long_description": "<optional>",
  "author": { "name": "<Vendor>", "url": "<https://vendor.com/>" },
  "homepage": "<optional>",
  "documentation": "<optional>",
  "support": "<optional>",
  "icon": "data:image/svg+xml;base64,...", // see below
  "tools": [{ "name": "...", "description"    
   
   
   
   
   
   
        
          
                 
  
          
                       
               

Do NOT add evaluation-era fields (quality_score, last_scraped_at, evaluation_model, framework, dependencies, raw_dependencies, protocol_features, score_breakdown) — the pipeline that filled them is gone and the schema no longer has them.

Icon: prefer the vendor's official SVG, inlined as a base64 data URI. Iconify shortcut: curl -s https://api.iconify.design/logos/<slug>.svg | base64. Decode and eyeball it: static SVG only — no <script>, no external refs, no event handlers.

Category: the allowed values live in the website repo, app/app/mcp-catalog/schemas.ts → McpServerCategorySchema (https://github.com/archestra-ai/website/blob/main/app/app/mcp-catalog/schemas.ts). When in doubt grep existing entries: grep -h '"category"' mcp-catalog/data/mcp-evaluations/*.json | sort | uniq -c.

4. Validate before the PR

# JSON parses, name matches filename, URL present exactly once
python3 - << 'EOF'
import json
name = "<derived name>"
m = json.load(open(f"mcp-catalog/data/mcp-evaluations/{name}.json"))
assert m["name"] == name, "name != filename"
servers = json.load(open("mcp-catalog/data/mcp-servers.json"))
assert servers.count("<url>") == 1, "URL missing or duplicated in mcp-servers.json"
print("ok")
EOF

Format with prettier at print width 120 (the website's setting): npx prettier --write --print-width 120 mcp-catalog/data/mcp-evaluations/<name>.json mcp-catalog/data/mcp-servers.json

If an archestra-ai/website checkout sits next to this repo, run the full schema validation from website/app: pnpm catalog:validate (it reads the adjacent checkout).

5. Open the PR

One PR against this repo, both files, title feat(mcp-catalog): add <display_name> MCP server. In the body: what the server is, transport/auth (as verified by the live probe, not the docs), and the derived-name rule applied. A merged PR triggers a website deploy automatically — no other repo needs changes unless you added a new category (that enum lives in the website repo).