@gatefare/mcp

Give your AI agent a wallet and a marketplace.

@gatefare/mcp is a Model Context Protocol server that connects Claude Desktop, Cursor, or any MCP-compatible agent to the Gatefare catalog of paid HTTP APIs. Payments settle as USDC on Base via the open x402 standard — no SaaS keys, no subscriptions, no escrow. Non-custodial: signing happens locally; the private key never leaves your machine.

┌─────────────┐                ┌──────────────┐                ┌─────────────────┐
│ Claude /    │   MCP stdio    │ @gatefare/mcp│  HTTP + x402   │ gatefare.io     │
│ Cursor /    │ ─────────────► │   (this repo)│ ─────────────► │ proxy +         │
│ your agent  │                │              │                │ catalog         │
└─────────────┘                └──────┬───────┘                └─────────────────┘
                                      │
                                      │ EIP-3009 sign
                                      ▼
                                ┌─────────────┐
                                │  Base USDC  │
                                └─────────────┘

Quick start

1. Drop into your client

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json or project-level .cursor/mcp.json:

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"]
    }
  }
}

Restart the client. The agent now has 5 read-only tools — discovery + safety. Try:

"Search Gatefare for weather APIs."

2. Add a wallet to make paid calls

Add env to the same config:

{
  "mcpServers": {
    "gatefare": {
      "command": "npx",
      "args": ["-y", "@gatefare/mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0xYOUR_KEY",
        "WALLET_BUDGET_USD": "5.00"
      }
    }
  }
}

Buyer tools (call_api, get_wallet_balance, estimate_cost) become available. The WALLET_BUDGET_USD cap is a runtime safety net — for a hard cap, fund the wallet with only what you're willing to spend.

"What's London's weather right now? Spend up to $0.001."

3. (Optional) Publish your own APIs

Get a PAT at gatefare.io/dashboard/tokens and add:

"env": {
  "GATEFARE_PAT": "gfpat_..."
}

Publisher tools (register_api, list_my_apis, update_api, get_revenue, distribute) appear.

"Publish my API at https://api.example.com/sentiment for $0.001 per call."

Tools

13 tools across 4 domains. Tools auto-register based on which env vars are set — the agent never sees a tool it can't use.

Discovery — always available

Tool	Description
`gatefare.search_apis`	Full-text search the catalog with filters (price, category, sort)
`gatefare.get_api`	Full details for one API by slug or `handle/urlName`
`gatefare.list_categories`	All categories with API counts
`gatefare.suggest`	Autocomplete suggestions for a query string

Buyer — needs `WALLET_PRIVATE_KEY`

Tool	Description
`gatefare.call_api`	Make a paid call. Handles 402 → sign → retry automatically
`gatefare.get_wallet_balance`	USDC + ETH on Base, plus remaining runtime budget
`gatefare.estimate_cost`	Project total cost for N planned calls

Publisher — needs `GATEFARE_PAT`

Tool	Description
`gatefare.register_api`	Publish a new paid API
`gatefare.list_my_apis`	Your published APIs with stats
`gatefare.update_api`	Edit metadata, price, target URL
`gatefare.get_revenue`	Revenue time series + totals
`gatefare.distribute`	Trigger on-chain `distribute()` payout (destructive)

Safety — always available

Tool	Description
`gatefare.report_abuse`	Report a malicious / stolen API (DMCA, fraud, malware…)

Configuration

Var	Default	Required for
`GATEFARE_BASE_URL`	`https://gatefare.io`	— (override for self-hosted)
`WALLET_PRIVATE_KEY`	—	Any buyer tool
`WALLET_BUDGET_USD`	unlimited	Optional spend cap
`WALLET_NETWORK`	`eip155:8453`	`eip155:84532` for Sepolia testnet
`GATEFARE_PAT`	—	Any publisher tool
`LOG_LEVEL`	`info`	`debug` for verbose stderr

Examples

Discover & buy in one breath (Claude Desktop)

You: Find me a sub-$0.001 weather API and call it for "Tokyo".

Claude: Calling gatefare.search_apis with max_price: 0.001…
Found demo-weather by @alice at $0.001/call.
Calling gatefare.call_api with slug: "demo-weather", query: {city: "Tokyo"}…
Tokyo is 22°C, partly cloudy. Paid 0.001 USDC. Receipt: settled-tx-0x9a…

Programmatic — Python agent

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server = StdioServerParameters(
    command="npx",
    args=["-y", "@gatefare/mcp"],
    env={"WALLET_PRIVATE_KEY": "0x...", "WALLET_BUDGET_USD": "1.00"},
)

async with stdio_client(server) as (r, w):
    async with ClientSession(r, w) as s:
        await s.initialize()
        result = await s.call_tool(
            "gatefare.call_api",
            arguments={"slug": "demo-weather", "query": {"city": "Tokyo"}},
        )
        print(result.content[0].text)

See examples/ for runnable variants: Claude Desktop, Cursor, Python, TypeScript, and a pure-discovery walkthrough.

Not building an AI agent? Picking the right tool

If you want to pay for x402 APIs from a backend (no agent), use Coinbase's official x402 SDKs — x402-python (PyPI), coinbase/x402/go, …/java, or @x402/fetch. They handle the payment flow; you don't need this MCP server.

If you want to browse the Gatefare catalog from any language, hit the REST API directly: gatefare.io/api/catalog (OpenAPI 3.1 spec).

Full breakdown of which tool fits which use case in docs/integrations.md.

Direct CLI (for debugging)

# Run the server in foreground; talks JSON-RPC over stdio.
npx -y @gatefare/mcp

# In another terminal, send a frame:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  npx -y @gatefare/mcp

Errors

Tool results include isError: true and a structured body { error: <code>, message: <human>, details?: <any> }. Codes are stable — agents can switch on them for retry / surfacing logic.

Code	Meaning
`INVALID_INPUT`	Input failed zod validation
`WALLET_NOT_CONFIGURED`	Set `WALLET_PRIVATE_KEY` for buyer tools
`PAT_NOT_CONFIGURED`	Set `GATEFARE_PAT` for publisher tools
`BUDGET_EXHAUSTED`	Runtime budget cap hit
`INSUFFICIENT_BALANCE`	Wallet doesn't have enough USDC
`PRICE_TOO_HIGH`	Server's price exceeds your `max_price`
`API_NOT_FOUND`	Slug doesn't exist or is suspended
`UPSTREAM_ERROR`	Paid API returned non-2xx, or its 402 was malformed
`RATE_LIMITED`	Gatefare rate-limited the request
`NETWORK_ERROR`	Could not reach Gatefare
`GATEFARE_API_ERROR`	Gatefare returned a 4xx / 5xx

How it works (the 30-second version)

The agent calls gatefare.call_api { slug: "demo-weather", … }.
We GET https://gatefare.io/p/demo-weather (no payment yet).
The Gatefare proxy returns 402 Payment Required with accepts: [{network, payTo, maxAmountRequired, …}].
We sign an EIP-3009 transferWithAuthorization for that exact amount and recipient on the configured network.
We retry the request with the signed X-Payment header (base64-encoded JSON, x402 v2).
Gatefare verifies the signature, settles the USDC transfer, and proxies the call to the upstream API.
We hand the upstream response (and a payment receipt) back to the agent.

The signature is single-use, time-bounded, and never leaves your machine for any purpose other than this exact transfer to this exact payTo. The private key is never logged.

Security

Non-custodial. Private keys live in your env, signing happens locally, no Gatefare service ever sees them.
Network confusion-resistant. A malicious gateway returning Sepolia-only requirements to a mainnet user is rejected — we never sign for a chain the user didn't configure.
Cryptographically random nonces. No Date.now()-based collisions.
Validity window clamped to 1 hour even if the server requests more.
Strict input validation. Slugs are ^[a-z0-9_-]+$ and URL-encoded; no path traversal. targetUrl blocks file://, localhost, cloud metadata IPs, .local, and .internal hosts at registration time.
Secret hygiene. Tests assert that the private key and PAT never appear in stderr / stdout, ever.

Development

git clone https://github.com/gatefareio/mcp-server.git
cd mcp-server
npm install
npm run typecheck
npm test                  # 138 unit tests
npm run test:e2e          # 10 e2e tests against live gatefare.io (set GATEFARE_E2E=1)
npm run build

To use a local checkout in your client config:

npm link
# in claude_desktop_config.json:
#   "command": "gatefare-mcp"

Architecture

src/
├── index.ts        # entry — wires stdio transport
├── server.ts       # McpServer instance + tool registration
├── config.ts       # env parsing, capability detection
├── client.ts       # REST client (wraps fetch)
├── x402.ts         # 402 parsing + EIP-3009 signing
├── types.ts        # shared types + GatefareError
└── tools/
    ├── discovery.ts   # search_apis, get_api, list_categories, suggest
    ├── buyer.ts       # call_api, get_wallet_balance, estimate_cost
    ├── publisher.ts   # register_api, list_my_apis, update_api, get_revenue, distribute
    └── safety.ts      # report_abuse

Test layout

tests/
├── config.test.ts         # env parsing edges
├── client.test.ts         # HTTP client error mapping
├── x402.test.ts           # signing + parsing primitives
├── x402-flow.test.ts      # full 402 → sign → retry handshake (mocked fetch)
├── server.test.ts         # capability-driven tool registration
├── init.test.ts           # subprocess: bootstrap, env crashes, secret leakage
├── stdio-protocol.test.ts # stdout pollution + recovery from tool errors
├── stability.test.ts      # 100 concurrent calls, memory baseline, ReDoS
├── tools/
│   ├── discovery.test.ts
│   ├── buyer.test.ts
│   ├── buyer-flow.test.ts
│   ├── publisher.test.ts
│   └── safety.test.ts
└── integration/
    └── e2e.test.ts        # real gatefare.io, gated by GATEFARE_E2E=1

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for the workflow, style guide, and how to add a new tool.

Related packages

Gatefare ships three first-party packages. They share the same x402 protocol and the same backend, so a project can mix them as needed:

Package	Where	When to use
`@gatefare/mcp` (this one)	npm	Drop into Claude Desktop / Cursor / any MCP host to give the agent tools for catalog discovery + paid calls
`@gatefare/client`	npm	TypeScript / JavaScript agents that pay APIs in code, outside MCP
`gatefare`	PyPI	Python agents (LangChain, LlamaIndex, etc.)

License

MIT © Gatefare

Links

🌐 Marketplace: gatefare.io
📚 API docs: gatefare.io/docs
🤖 LLM context (single file): gatefare.io/llms-full.txt
📐 OpenAPI spec: gatefare.io/openapi.json
🐦 Twitter: @Gatefareio
🔌 Model Context Protocol: modelcontextprotocol.io
💸 x402 standard: x402.org

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.npmignore		.npmignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

@gatefare/mcp

Quick start

1. Drop into your client

2. Add a wallet to make paid calls

3. (Optional) Publish your own APIs

Tools

Discovery — always available

Buyer — needs `WALLET_PRIVATE_KEY`

Publisher — needs `GATEFARE_PAT`

Safety — always available

Configuration

Examples

Discover & buy in one breath (Claude Desktop)

Programmatic — Python agent

Not building an AI agent? Picking the right tool

Direct CLI (for debugging)

Errors

How it works (the 30-second version)

Security

Development

Architecture

Test layout

Contributing

Related packages

License

Links

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

@gatefare/mcp

Quick start

1. Drop into your client

2. Add a wallet to make paid calls

3. (Optional) Publish your own APIs

Tools

Discovery — always available

Buyer — needs WALLET_PRIVATE_KEY

Publisher — needs GATEFARE_PAT

Safety — always available

Configuration

Examples

Discover & buy in one breath (Claude Desktop)

Programmatic — Python agent

Not building an AI agent? Picking the right tool

Direct CLI (for debugging)

Errors

How it works (the 30-second version)

Security

Development

Architecture

Test layout

Contributing

Related packages

License

Links

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Buyer — needs `WALLET_PRIVATE_KEY`

Publisher — needs `GATEFARE_PAT`

Packages