MCP Connector Kit

Connect AI agents to real APIs through one MCP gateway—not a pile of one-off scripts.

If you landed here without context: this repo is a TypeScript monorepo for building and running Model Context Protocol servers that wrap third-party HTTP APIs (Wikipedia, GitHub, search providers, and similar). You get shared rate limits, retries, caching, schema validation, metrics, and offline contract replay so CI catches upstream drift before production does.

Social preview image: https://mck-web-production.up.railway.app/opengraph-image

What problem does this solve?

MCP clients (Cursor, Claude Desktop, custom agents) need tools—search, fetch a page, query GitHub, and so on. Wiring each API yourself means repeating the same concerns: auth, timeouts, retries, rate limits, input/output validation, and “did the vendor change their JSON again?”

MCP Connector Kit centralizes that in:

1. @mck/core — HTTP client with allowlists, breaker, token bucket, cache, Zod validation, structured errors.

2. @mck/server — MCP over stdio or Streamable HTTP (POST /mcp), plus /healthz, /readyz, /metrics, optional OAuth metadata.

3. @mck/gateway — One process that loads many sources (connectors) and exposes them as MCP tools, with free vs paid SKU filtering.

4. sources/* — Thin adapters per upstream; each ships fixtures/*.contract.json replayed in CI via @mck/testing.

You add a new upstream by defining tools and recording fixtures—not by forking ad-hoc MCP servers.

Related MCP server: MCP Gateway

Who is this for?

How a request flows

MCP client → stdio or HTTP → @mck/gateway → source registry → tool (Zod in/out) → allowlisted HTTP → upstream API

The same path runs in production and in CI contract replay (undici mocks + recorded fixtures)—see Architecture.

Trust-tier sources (today)

Details: Trust tier · Hosted gateway SKU

Quick start

Prerequisites: Node 22+, pnpm 9+.

git clone https://github.com/o-mid/mcp-connector-kit.git
cd mcp-connector-kit
pnpm install
pnpm build

Local gateway (stdio, free sources):

MCK_SOURCE_PROFILE=default node apps/gateway/dist/cli.js

Named toolkits (research = Wikipedia + OpenAlex + Open Library, geo = Open-Meteo + USGS + World Bank, daily = Frankfurter + HN + Open-Meteo):

MCK_SOURCE_PROFILE=research node apps/gateway/dist/cli.js

Trust profile (paid SKU — needs upstream API keys in env):

MCK_SOURCE_PROFILE=trust MCK_SKU=paid node apps/gateway/dist/cli.js

HTTP transport (Streamable MCP at POST /mcp). New installs use canonical tool names (wikipedia.wiki_search). Set MCK_LEGACY_TOOL_NAMES=true only if an existing client still calls bare names (wiki_search). The Docker image keeps legacy names on so hosted Cursor configs do not break; see Trust tier.

MCK_SOURCE_PROFILE=default MCK_TRANSPORT=http PORT=8080 node apps/gateway/dist/cli.js

Health checks: GET /healthz · Readiness: GET /readyz · Prometheus: GET /metrics

Public Wikipedia demo (no API key; fixture + Wikipedia only):

MCK_PUBLIC_DEMO=true MCK_TRANSPORT=http PORT=8080 node apps/gateway/dist/cli.js

POST /demo/mcp · GET /demo/healthz. /mcp is unchanged and still requires MCK_API_KEYS when that variable is set.

@mck/core, @mck/server, @mck/gateway, and @mck/cli are the package names the release workflow publishes. They are not on the public npm registry yet. The clone above is the install that runs. Registry metadata for the hosted URL is registry/server.json; submit it with mcp-publisher.

Cursor (Streamable HTTP)

Hosted gateway (bearer token required):

{
  "mcpServers": {
    "mck": {
      "url": "https://mcp-connector-kit-production.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GATEWAY_KEY"
      }
    }
  }
}

Wikipedia demo, once MCK_PUBLIC_DEMO=true is set on the gateway:

{
  "mcpServers": {
    "mck-wikipedia": {
      "url": "https://mcp-connector-kit-production.up.railway.app/demo/mcp"
    }
  }
}

One-click install and the Claude Desktop / LangChain snippets: Connect.

Marketing site (Next.js):

pnpm web:dev   # http://localhost:3000

Environment variables: see .env.example (MCK_SOURCES, MCK_SOURCE_PROFILE, MCK_SKU, MCK_TRANSPORT, MCK_LEGACY_TOOL_NAMES, and upstream keys).

Packages

Documentation

License

MIT · o-mid/mcp-connector-kit