Developers & agents

AllMCPs API Documentation

Public, CORS-friendly endpoints for searching MCP servers, embedding badges, and plugging the AllMCPs directory into AI agents. No API key required for read endpoints. Also available as the official allmcps-server CLI / MCP server on npm, and as a full AllMCPs OpenAPI spec.

Quick start

Search the directory from any HTTP client or agent:

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

Endpoints

• GET/api/v1/search

  Search servers

  Keyword and category search over active listings. Returns install hints with confidence scores.

  https://allmcps.com/api/v1/search?q=github&limit=5
• GET/api/v1/servers/{id}

  Get server by ID

  Single listing with quality score, popularity signals, and public metadata.

  https://allmcps.com/api/v1/servers/github-github-mcp-server
• GET/api/v1/mcp/{id}/markdown

  Markdown detail

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

  https://allmcps.com/mcp/github-github-mcp-server.md
• GET/api/v1/health

  Service health

  Lightweight health probe for monitors and agents.

  https://allmcps.com/api/v1/health
• GET/api/badge/{id}

  SVG badge

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

  https://allmcps.com/api/badge/github-github-mcp-server?style=shield
• 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.

  POST https://allmcps.com/api/v1/submit
• 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.

  https://allmcps.com/api/v1/categories
• POST/api/v1/agent/register

  Agent registration

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

  POST https://allmcps.com/api/v1/agent/register
• POST/api/v1/agent/register/confirm

  Confirm registration & mint Bearer token

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

  POST https://allmcps.com/api/v1/agent/register/confirm
• 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.

  POST https://allmcps.com/api/v1/agent/claim
• POST/api/v1/agent/revoke

  Revoke agent token

  Revoke an active agent Bearer token.

  POST https://allmcps.com/api/v1/agent/revoke
• POST/api/v1/inspect

  Live MCP inspector

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

  POST https://allmcps.com/api/v1/inspect
• GET/api/mcp

  Remote MCP server

  AllMCPs itself as a remote MCP server: search, install configs, categories, boosting, and a fully schema'd submit_mcp_server tool (call tools/list for the exact category/pricing/auth/maintenance enum values). Also available as the allmcps-server npm package (stdio bridge to this same endpoint).

  https://allmcps.com/api/mcp

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.