Skip to main content

MCPBundles Directory API — Search and Call Tools Over HTTP

Short answer

If you are building an agent, integration, or script that should discover MCP servers and sometimes run a tool without wiring up MCP JSON-RPC, use the Directory API v1 at https://www.mcpbundles.com/api/directory/v1. Search the same index as the MCPBundles directory, fetch per-server detail (tools and connect hints), and POST tool calls when the listing allows it. The full machine contract lives in agents.md and OpenAPI. /api/registry is a separate, read-only MCP Registry-shaped feed for IDE galleries such as VS Code — not for invoking tools.

Tested withMCPBundles Directory API v1 (OpenAPI 3.1)MCP Registry adapter at /api/registry (read-only gallery shape)Checked 9 Nov 2026

By Tony LewisHow we test these guides

When to use which surface​

GoalUse
Headless search → detail → HTTP tool callDirectory API v1 (/api/directory/v1)
VS Code chat.mcp.gallery.serviceUrl or other registry OpenAPI clients/api/registry (metadata only)
Human browse and one-click connect in an AI appDirectory website and /skills/{slug} pages
In-browser tools on wwwWebMCP on skill pages — not documented for server-side fetch clients

You do not need a MCPBundles account to read the Directory API or registry adapter. Some listings only support install handoffs (connect in Cursor, Claude, and so on); the detail response tells you which case applies.

Start from discovery​

GET the API root once. The JSON tells you where search, detail, invoke, and OpenAPI live:

curl -sS "https://www.mcpbundles.com/api/directory/v1"

Important fields include search, serverDetail, invokeTool, openApi, documentation (link to agents.md), and registryAdapter (link to /api/registry).

Search the index​

Ranked full-text search matches titles, descriptions, tools, and publisher names:

curl -sS "https://www.mcpbundles.com/api/directory/v1/search?q=sunrise&limit=5"

Each hit includes directorySlug, pageUrl, connectPath, and supportsAnonymousDirectoryCall. Use connectPath to see whether the row is managed on MCPBundles, importable as a remote MCP URL, or browse-only. Optional filters include connect_path=managed, harvest_only=true, and kind=webmcp. Pagination uses cursor from pagination.nextCursor.

Server detail and optional live refresh​

Load tools (stored preview by default) and agent metadata:

curl -sS "https://www.mcpbundles.com/api/directory/v1/servers/sunrise-sunset"

Add ?live=1 when you need a fresh probe against a remote upstream (slower). Fields such as agentAction, installLinks, and callUrl describe what a headless client may do versus what needs a human install step.

Invoke a tool (when eligible)​

For listings that allow anonymous directory calls, POST a JSON body of tool arguments to the invoke path. Tool names match the detail payload (hashless Python names or MCP names from the preview):

curl -sS -X POST \
  "https://www.mcpbundles.com/api/directory/v1/servers/sunrise-sunset/tools/sunrise_sunset_get_sun_times" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 51.5074, "longitude": -0.1278, "date": "2026-10-27"}'

If the listing is install-only, use installLinks from detail and do not claim the tool ran.

Commercial use​

You can use the Directory API without an account, and most scripts never get near a limit. If you're building a product on it, such as a tool picker that searches while people type, you'll want Directory API Pro. It costs $299 a month for your workspace.

FreeDirectory API Pro
Directory v12 requests/second and 30/minute10 requests/second and 300/minute
Registry adapter2 requests/second and 30/minute10 requests/second and 300/minute
CounterPer IP, or per workspace if you send a keyPer workspace
Price$0$299/month

Getting set up. Pro uses the API key you already create under Settings → Security, so you don't need a new one. Send it on every request:

curl -sS "https://www.mcpbundles.com/api/directory/v1/search?q=invoices" \
  -H "Authorization: Bearer mb_your_key"

Then subscribe from pricing. Your next request is on Pro.

A few things worth knowing:

  • A key helps even on Free. Without a key, the limit is counted per IP. With a key, it's counted per workspace, so jobs that share an office or cloud address don't use up each other's share.
  • The client name doesn't matter. The User-Agent header never changes your limit. Search engines and AI crawlers get the free tier like everyone else.
  • Directory and registry are counted separately. Busy registry traffic doesn't use up your directory requests.
  • You'll know when you've hit it. Going over returns 429 with a Retry-After header. On Free, the body has kind: "upgrade_required", an upgrade_url, and an assistant_message an AI agent can read: it tells the agent to pass the upgrade link to a person instead of retrying. On Pro, the body has kind: "rate_limited" and just asks you to back off. Every response says your tier in X-Directory-Api-Tier, so you can watch it in your logs.
  • A failed payment doesn't break anything. You drop back to the free limits until the card goes through.
  • Commercial use needs Pro, and nobody may resell the data. Free covers evaluation, personal projects, research, and helping someone find a server. Using results inside a product you run for customers needs Pro. On any tier, you can't sell or republish the directory as a dataset, feed, API, or competing index. See Directory API and registry license.

If you need more than Pro, email us with your workspace and the rate you need.

Registry adapter (IDE galleries only)​

MCPBundles also exposes a subset of the directory index in the official MCP Registry API shape:

  • Gallery base URL: https://www.mcpbundles.com/api/registry (VS Code appends /v0.1/servers to this base).
  • List / search: GET https://www.mcpbundles.com/api/registry/v0.1/servers?search=stripe&limit=30

That API is read-only metadata for registry-aware clients. It does not replace Directory v1 search semantics or HTTP invoke. For the official registry at registry.modelcontextprotocol.io, see The MCP Registry.

Canonical references for agents​

Automated clients should treat these as source of truth (this guide is a human summary):

Directory browse pages and skill pages also support Accept: text/markdown and .md URLs for markdown snapshots; see agents.md for rules.

FAQ​

Do I need MCP JSON-RPC to use the Directory API?

No. v1 is plain HTTPS: GET for search and detail, POST for tool invoke when the listing supports it. MCP wire URLs are still the right path after a user connects a server in Cursor, Claude, or another host.

Should I point VS Code at /api/directory/v1?

No. VS Code gallery policy expects the MCP Registry service URL shape. Use https://www.mcpbundles.com/api/registry as chat.mcp.gallery.serviceUrl. Use Directory v1 for your own search-and-call integrations.

Is every listing callable over HTTP?

No. Read supportsAnonymousDirectoryCall and agentAction on search and detail. Remote servers that need upstream sign-in, or WebMCP-only listings, may be install or browse only.

Where is the full field reference?

agents.md and the v1 OpenAPI document. Regenerate agents.md from the repo with make generate-public-agents-md when the platform contract changes.

Do I need a new API key for Directory API Pro?

No. Create a workspace API key under Settings → Security, the same key the rest of MCPBundles uses, and send it as Authorization: Bearer. Then subscribe to Directory API on Plan & billing. The license is on the workspace, not on a second token.

Does naming my client Amazonbot or Googlebot raise the limit?

No. The User-Agent header is ignored for access. Anonymous reads stay on the free per-IP cap. Pro is a paid workspace license.

Is Directory API Pro a connector plan or a listing upgrade?

Neither. Connector plans meter your own MCP tool calls. A company page is a listing you maintain. Directory API Pro only raises the cap on Directory v1 and the registry adapter.