MCP Server

@sweepster/mcp is a Model Context Protocol stdio server that exposes the Sweepster API as tools for AI agents and Claude Code. Use it to let an AI assistant drive sweeps and manage your builder account — without writing API client code.

Signing note. The live gasless sweep path is EIP-7702 — the user EIP-712-signs the SweepDelegate SweepOrder (via signTypedData) plus an EIP-7702 authorization off-chain (see the Signing guide). The build_permit2_typeddata codegen tool below targets the retained on-chain Permit2 path and is not the path the product uses; prefer get_quote → gen_integration_snippet for an end-to-end flow.

Install

npm install -g @sweepster/mcp
# or
npx @sweepster/mcp

Configuration

The server reads its configuration from environment variables:

Variable	Required	Description
SWEEPSTER_ORCHESTRATOR_URL	Yes	Orchestrator base URL, e.g. https://api.sweepster.xyz
SWEEPSTER_BUILDER_URL	Yes	Builder-backend base URL, e.g. https://builders.sweepster.xyz
SWEEPSTER_API_KEY	No	Your builder API key (enables attribution + attribute tool)
SWEEPSTER_ADMIN_TOKEN	No	Admin token (enables register_builder tool)

Register in Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "sweepster": {
      "command": "npx",
      "args": ["@sweepster/mcp"],
      "env": {
        "SWEEPSTER_ORCHESTRATOR_URL": "https://api.sweepster.xyz",
        "SWEEPSTER_BUILDER_URL": "https://builders.sweepster.xyz",
        "SWEEPSTER_API_KEY": "sk_live_..."
      }
    }
  }
}

Or via the CLI:

claude mcp add sweepster \
  --command npx \
  --args @sweepster/mcp \
  --env SWEEPSTER_ORCHESTRATOR_URL=https://api.sweepster.xyz \
  --env SWEEPSTER_BUILDER_URL=https://builders.sweepster.xyz \
  --env SWEEPSTER_API_KEY=sk_live_...

Register in a generic MCP client

{
  "name": "sweepster",
  "transport": "stdio",
  "command": "npx @sweepster/mcp",
  "env": {
    "SWEEPSTER_ORCHESTRATOR_URL": "https://api.sweepster.xyz",
    "SWEEPSTER_BUILDER_URL": "https://builders.sweepster.xyz",
    "SWEEPSTER_API_KEY": "sk_live_..."
  }
}

Available tools

get_quote

Request a sweep quote from the orchestrator.

Input:

{
  owner: string;            // user wallet address
  tokenIn: string;          // source token address
  amountIn: string;         // amount in smallest unit (decimal string)
  tokenOut: string;         // destination token address
  destination: string;      // recipient address
  destChainId: number;      // destination chain ID
  tier: "tier1" | "tier2" | "tier3";
  subscriptionActive: boolean;
  userId: string;
  route?: string;           // e.g. "base->arbitrum"
  apiKey?: string;          // builder API key (optional, uses SWEEPSTER_API_KEY env if omitted)
}

Returns: { quote, order } — the quote metadata and unsigned SweepOrderWire.

---

submit_signed

Submit a signed intent to the orchestrator.

Input:

{
  quoteId: string;    // from get_quote response
  signature: string;  // the user's order-digest signature "0x..."
}

Returns: { id, status, txHash? }

For the live EIP-7702 path, POST /intents also requires the user's EIP-7702 authorization. Use the Signing guide + a direct POST /intents call for production submission; the gen_integration_snippet tool emits the full flow.

---

get_intent_status

Poll the status of a submitted intent.

Input:

{ id: string }    // intent ID

Returns: { id, status, txHash?, crossChain }

---

build_permit2_typeddata

Pure codegen — builds the EIP-712 typed data for a Permit2 witness signature. No network call.

Targets the retained-but-unused on-chain Permit2 path. The live product signs the EIP-7702 SweepDelegate digest instead (see the Signing guide).

Input:

{
  order: SweepOrderWire;  // the order from get_quote
  spender: string;        // SweepRouter contract address
  chainId: number;        // source chain ID
}

Returns: The full EIP-712 typed data object ({ domain, types, primaryType, message }).

---

gen_integration_snippet

Pure codegen — generates a copy-paste TypeScript snippet wiring quote → sign (viem) → submit.

Input:

{
  orchestratorUrl?: string;   // defaults to SWEEPSTER_ORCHESTRATOR_URL
  builderApiKey?: string;     // defaults to SWEEPSTER_API_KEY
  sweepRouter?: string;       // SweepRouter contract address
  sourceChainId?: number;     // source chain (default 8453)
}

Returns: A complete TypeScript snippet as a string.

---

attribute

Resolve attribution for your builder API key. Confirms the key is active and returns your fee configuration.

Auth: Uses SWEEPSTER_API_KEY env variable.

Input: (none)

Returns: { builderId, builderBps, maxBuilderBps, payoutAddress }

---

list_accruals

List the accrual ledger for a builder. Uses SWEEPSTER_ADMIN_TOKEN.

Input:

{ builderId: string }

Returns: { builderId, balances: [{ token, amount }] }

---

register_builder

Register a new builder. Only available when SWEEPSTER_ADMIN_TOKEN is set.

Input:

{
  id: string;
  name: string;
  builderBps: number;
  maxBuilderBps: number;
  payoutAddress: string;
}

Returns: { builder, apiKey } — the API key is shown once.

---

Example agent usage

With the MCP server registered, you can ask an AI agent:

"Get a quote to sweep 1000 USDC from Base to Arbitrum for wallet 0x...,
then generate an integration snippet showing what the user needs to sign."

The agent will:

1. Call get_quote with your parameters
2. Call gen_integration_snippet to produce the quote → sign → submit flow
3. Present the snippet and the exact order fields the user is authorizing

Or:

"Check if my builder API key is active and show my current accrual balance."

The agent calls attribute then list_accruals.

Security notes

• SWEEPSTER_API_KEY is passed as the x-api-key header to the builder-backend — never as a JSON body field.
• SWEEPSTER_ADMIN_TOKEN gates the register_builder tool; omit it unless you need admin operations.
• Never expose your MCP server's environment variables in client-side code or public repositories.

Related

• Skills — sweepster-integration — guided Claude Code skill for full builder integration
• Integration Guide