AllMCPs API Documentation

Quick start

Search the directory from any HTTP client or agent:

Endpoints

• GET/api/v1/search

  Search servers

  Keyword, semantic and category search over listed servers, ranked toward ones we have seen run. Optional transport=stdio|remote and verified=1 filters. Returns install hints with confidence scores.

  $curl "https://allmcps.com/api/v1/search?q=github&limit=5"

  Open example ↗
• GET/api/v1/servers/{id}

  Get server by ID

  Single listing with quality score, popularity signals, public metadata, and a configs array with ready-to-paste setup for each MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Zed, Codex, Gemini CLI, JetBrains, Roo Code, Continue, LM Studio). configs is null when the install is not confirmed. Pending, rejected and flagged listings return 404.

  $curl "https://allmcps.com/api/v1/servers/github-github-mcp-server"

  Open example ↗
• GET/api/v1/mcp/{id}/markdown

  Markdown detail

  LLM-friendly Markdown for a listing. Also available via Accept: text/markdown on /mcp/{id}.

  $curl "https://allmcps.com/mcp/github-github-mcp-server.md"

  Open example ↗
• GET/api/v1/health

  Service health

  Lightweight health probe for monitors and agents.

  $curl "https://allmcps.com/api/v1/health"

  Open example ↗
• GET/api/badge/{id}

  SVG badge

  Dynamic badge for READMEs and docs. Use dofollow links when embedding for reciprocal SEO.

  $curl "https://allmcps.com/api/badge/github-github-mcp-server?style=shield"

  Open example ↗
• POST/api/v1/submit

  Agent submission

  Submit a new MCP listing programmatically (requires email). Accepts the same optional enrichment fields as the /api/mcp submit_mcp_server tool (tags, license, authType, pricingModel, maintenanceStatus, compatibleClients, supportUrl, suggested install command/args). Human form is /submit.

  $curl -X POST "https://allmcps.com/api/v1/submit" -H "Content-Type: application/json" -d '{}'
• GET/api/v1/categories

  List categories

  Every category AllMCPs accepts, with label, emoji, slug, and group — use to pick a valid "category" value before submitting.

  $curl "https://allmcps.com/api/v1/categories"

  Open example ↗
• POST/api/v1/agent/register

  Agent registration

  Register an AI agent with email to receive a 6-digit verification code.

  $curl -X POST "https://allmcps.com/api/v1/agent/register" -H "Content-Type: application/json" -d '{}'
• POST/api/v1/agent/register/confirm

  Confirm registration & mint Bearer token

  Exchange 6-digit confirmation code for an amcp_... agent Bearer token.

  $curl -X POST "https://allmcps.com/api/v1/agent/register/confirm" -H "Content-Type: application/json" -d '{}'
• POST/api/v1/agent/claim

  Claim listing via agent

  Claim an MCP server listing programmatically using DNS TXT record, site badge, or GitHub README proof.

  $curl -X POST "https://allmcps.com/api/v1/agent/claim" -H "Content-Type: application/json" -d '{}'
• POST/api/v1/agent/revoke

  Revoke agent token

  Revoke an active agent Bearer token.

  $curl -X POST "https://allmcps.com/api/v1/agent/revoke" -H "Content-Type: application/json" -d '{}'
• POST/api/v1/inspect

  Live MCP inspector

  Proxy tools/list (and related methods) against a remote MCP endpoint for debugging.

  $curl -X POST "https://allmcps.com/api/v1/inspect" -H "Content-Type: application/json" -d '{}'
• GET/api/mcp

  Remote MCP server

  AllMCPs itself as a remote MCP server (protocol 2026-07-28, plus initialize-based 2025-11-25 and earlier): search with transport and verified-only filters, per-client install configs, alternatives, side-by-side comparison, stack recommendations, categories, boosting, and a fully schema'd submit_mcp_server tool (call tools/list for the exact enum values). Also available as the allmcps-server npm package (stdio bridge to this same endpoint).

  $curl "https://allmcps.com/api/mcp"

  Open example ↗

Category filtering

/api/v1/search?category= accepts any of the three forms returned by /api/v1/categories — the full stored name (emoji included), the plain label, or the slug. Matching is case-insensitive and ignores surrounding whitespace, so all three requests below return the same listings, and the response echoes back the canonical category it resolved to. Combine it with q= to apply both filters at once.

curl "https://allmcps.com/api/v1/search?category=databases&limit=5"
curl "https://allmcps.com/api/v1/search?category=Databases&limit=5"
curl --get --data-urlencode "category=🗄️ Databases" "https://allmcps.com/api/v1/search?limit=5"

# Both filters: Postgres servers within Databases only
curl "https://allmcps.com/api/v1/search?q=postgres&category=databases"

A category the directory doesn't have returns 400 with { "error": "unknown_category" } — an empty servers array always means "this category has no matching listings", never "that category name was wrong".

Scoped agent auth

Read endpoints (search, servers, categories, markdown, health) need no auth at all. Endpoints that mutate a listing require a scoped Bearer token — register via POST /api/v1/agent/register, requesting only the scopes you need in an optional scopes array (omit it to receive the full set below). A token used against an endpoint it wasn't granted a scope for gets back 403 {"error":"insufficient_scope","requiredScope":"...","grantedScopes":[...]} — never a silent failure or a downgraded response.

Machine-readable copies of this table: /.well-known/oauth-protected-resource (scopes_supported), the components.securitySchemes.agentBearerAuth.flows.clientCredentials.scopes map in the OpenAPI spec, and /auth.md's frontmatter, for the full registration → claim flow with example requests.

Versioning & deprecation policy

The API is URL-versioned (/api/v1/...); fields are added, not removed or repurposed, within a version. If an endpoint is ever deprecated it will carry a Deprecation: true response header and, once a removal date is set, a Sunset header, for at least 90 days before removal — announced on the blog. Nothing in v1 is currently deprecated.

Agent discovery

• Link response headers on every page point at this docs URL, the API catalog, and OAuth metadata.
• Markdown negotiation: send Accept: text/markdown or append ?format=md / .md to listing, blog, or category URLs.
• Machine catalog: /data.json and /llms-full.txt.

Questions or partnership ideas? Contact us.