@curless/mcp

Curless paywall adapter for MCP (Model Context Protocol) servers. Lets you charge incoming agents before your tool executes.

Not the agent-side client. If you want your agent to spend at Curless storefronts, use @curless/mcp-server instead. @curless/mcp is for sellers embedding payments inside their MCP server.

Install

npm i @curless/mcp

Quick start

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CurlessPaywall } from '@curless/mcp';

const paywall = new CurlessPaywall({ apiKey: process.env.CURLESS_KEY! });
const server = new Server({ name: 'acme-mcp', version: '1.0.0' });

paywall.registerPayableTool(
  server,
  {
    name: 'expensive_inference',
    description: 'Run model X',
    inputSchema: { type: 'object', properties: {} },
    pricing: { mode: 'metered', amount: 0.001, currency: 'USD' },
  },
  paywall.wrap(async (args, ctx) => {
    // ctx.curless.intent_id available
    // ctx.curless.meter(quantity, unitAmount?) for per-tick metering
    return { result: await runModel(args) };
  })
);

Agent token resolution

The agent token is resolved in order:

1. Per-call _meta.curless_agent_token field in the tool call request.
2. Session-level cache populated from MCP initialize request metadata (params._meta.curless_agent_token).

If no token is found, the tool returns an MCP error result with code: 'missing_agent_token'.

Authentication

export CURLESS_KEY=sk_live_...

Error responses

On charge failure the tool returns an MCP result with isError: true and a JSON body containing { error: { type, code, message } }.

Related packages

• @curless/server — Express / Next.js / Fastify / edge middleware
• @curless/auth — token verification helpers
• @curless/mcp-server — agent-side client (for end-users)