@apinator/mcp

Model Context Protocol server for Apinator. It lets an AI agent (Claude Code, Claude Desktop, Cursor, …) publish events, inspect channels and watch live traffic on your Apinator app, so it can build and debug realtime features end to end.

Setup

You need your app's ID, key, secret and cluster from the Apinator console. Node.js 18 or newer.

Claude Code

claude mcp add apinator \
  -e APINATOR_APP_ID=your-app-id \
  -e APINATOR_KEY=your-key \
  -e APINATOR_SECRET=your-secret \
  -e APINATOR_CLUSTER=eu \
  -- npx -y @apinator/mcp

Claude Desktop, Cursor and other clients (mcpServers JSON config)

{
  "mcpServers": {
    "apinator": {
      "command": "npx",
      "args": ["-y", "@apinator/mcp"],
      "env": {
        "APINATOR_APP_ID": "your-app-id",
        "APINATOR_KEY": "your-key",
        "APINATOR_SECRET": "your-secret",
        "APINATOR_CLUSTER": "eu"
      }
    }
  }
}

Environment variables

The server checks these at startup and exits with a message naming anything missing or malformed.

Related MCP server: console-stream-mcp

Tools

Every tool except publish_event is annotated readOnlyHint, so clients can auto-approve them.

A typical end-to-end check an agent runs: start watch_channel on a channel, trigger the code path that publishes (or call publish_event), and compare the payload with what the client expects. On cache- channels the last event is replayed to new subscribers, so a watch started after a publish still receives it.

Resources and prompts

• apinator://docs/llms.txt: the Apinator docs index, fetched from https://apinator.io/llms.txt.

• apinator://reference/protocol: frames, system events, error codes, channel types and the auth signature.

• Prompt add-realtime-feature: walks the agent through choosing channels, wiring the server and client SDKs, and verifying with watch_channel.

Security

• The secret stays in the server process. Tool results and errors are scrubbed of it, and API error bodies are shortened to a one-line message.

• publish_event reaches every subscriber of the channel. Set APINATOR_READ_ONLY=1 for an agent that should only look, or use a separate app for development.

• sign_channel_auth produces valid subscription signatures for any channel name. Only give the server to agents you would trust with your app's auth endpoint.

Development

npm install
npm run build
npm test                  # unit tests (mocked fetch, local fake WebSocket server)
npm run typecheck         # src and tests

Releases are cut by release-please from Conventional Commits on main; the release PR bumps package.json, updates CHANGELOG.md and tags, and the workflow then publishes to npm.

Maintainers with the Apinator backend checked out next to this repo (../../backend, or set BACKEND_DIR) can run the integration test and the MCP inspector against a throwaway local stack:

./scripts/local-stack.sh up       # builds the backend, starts Postgres/Redis in Docker on spare ports, seeds an app
npm run build && npm run test:integration
./scripts/local-stack.sh down

local-stack.sh up writes the local credentials to .local-stack/env. It also sets APINATOR_API_URL and APINATOR_WS_URL, which point the server at a non-production data plane.

License

MIT