MCP server

The Bytewells MCP server exposes the Store and Apify-compatible run API as MCP tools, so agents in Cursor, Claude Desktop, and other hosts can discover Actors, read their input schemas, start runs, and fetch dataset items and OUTPUT.

When a run is blocked with 402 rental-required and the listing offers time-window passes, call-actor buys the fare-capped quote (usually Flash) once and retries. It does not start monthly Stripe rentals.

ConnectCopy Anchor Link

Create an API key in the console (Settings → API keys). For stdio hosts:

{
  "mcpServers": {
    "bytewells": {
      "command": "npx",
      "args": ["-y", "@bytewells/mcp"],
      "env": {
        "BYTEWELLS_TOKEN": "cp_..."
      }
    }
  }
}

From a local checkout of this monorepo:

{
  "mcpServers": {
    "bytewells": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/bin.ts"],
      "env": {
        "BYTEWELLS_TOKEN": "cp_...",
        "BYTEWELLS_API_URL": "http://localhost:4100"
      }
    }
  }
}

EnvironmentCopy Anchor Link

Streamable HTTP mode: bytewells-mcp --transport http --port 8080. Authenticate each request with Authorization: Bearer <api key>.

ToolsCopy Anchor Link

Pinned actors from BYTEWELLS_ACTORS (or add-actor) appear as bytewells--{username}--{actorName} and accept that Actor’s input fields plus optional waitSecs and purchasePass.

Pass purchaseCopy Anchor Link

1. Agent calls call-actor (or a pinned Actor tool).
2. If the API returns 402 rental-required with data.passes.nextUse, the server GETs the pass offer.
3. If an active pass already covers now, it skips the buy and retries the run.
4. Otherwise it POSTs /v2/store/{user}/{actor}/passes with { tier, consentToShareContact: true, maxChargeCents } for the quoted tier, then retries the run once.
5. Set purchasePass: false on call-actor to stop at the error/quote. Set BYTEWELLS_MAX_PASS_CENTS to refuse expensive quotes.

Buying a pass debits prepaid credits and shares your account name and email with the Actor developer. Monthly rentals are out of scope for this server — use the console or API.

If purchase fails (insufficient-credits, publisher-not-payable, agent-purchases-disabled, payment-method-required, agent-limit-reached), the tool returns the error and any dashboard URL for a human to fix. An API key cannot enable agent spending by itself.

See Time-window passes for tiers, fare capping, and auto-purchase settings.

Typical agent flowCopy Anchor Link

1. search-actors with a query (for example "linkedin").
2. fetch-actor-details on the chosen actorRef and read inputSchema / exampleInput.
3. call-actor with valid input (and waitSecs if you need results in one step).
4. If the run is still running, get-actor-run then get-dataset-items.

RelatedCopy Anchor Link

• Passes
• Billing
• API reference
• Apify compatibility