BytewellsDocs

MCP server

Connect AI agents to Bytewells — search Actors, run them, and buy time-window passes when needed.

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.

Passes coming soon. Automatic pass purchase on 402 rental-required is implemented but disabled in production until time-window passes launch. Until then, rent the Actor or use a live rental.

When passes are enabled, a run blocked with 402 rental-required and a listing that offers time-window passes can be unblocked by call-actor buying the fare-capped quote (usually Flash) once and retrying. It does not start monthly Stripe rentals.

Connect

Bytewells runs a streamable HTTP MCP server at https://bytewells.com/mcp. Use it from Cursor (remote url), Claude Desktop (Connectors), or any host that speaks streamable HTTP.

Cursor — add to MCP settings (or .cursor/mcp.json):

{
  "mcpServers": {
    "bytewells": {
      "url": "https://bytewells.com/mcp"
    }
  }
}

Claude Desktop — Settings → Connectors → Add custom connector → https://bytewells.com/mcp (Claude does not support a url field in claude_desktop_config.json).

Alternatively (stdio config): npx -y mcp-remote https://bytewells.com/mcp in claude_desktop_config.json bridges Claude Desktop to the hosted server.

On first connect, the host discovers OAuth via /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server (dynamic client registration, authorization code with PKCE). The host opens the Bytewells sign-in page; after you log in, the agent uses your session—no API key paste required.

You can also send a console API key on every MCP request: Authorization: Bearer cp_... (Settings → API keys). OAuth and API keys expose the same tools.

Local stdio

Run the npm package on your machine when the host only supports stdio. Create an API key in the console (Settings → API keys):

{
  "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"
      }
    }
  }
}

Self-hosted HTTP

Run streamable HTTP yourself: bytewells-mcp --transport http --port 8080. Authenticate each request with Authorization: Bearer <api key>, or enable sign-in with MCP_PUBLIC_URL and MCP_OAUTH_SECRET (see package README).

Environment (stdio / self-hosted)

VariablePurpose
BYTEWELLS_TOKENAPI key (required for stdio)
BYTEWELLS_API_URLAPI base URL (default https://bytewells.com/api)
BYTEWELLS_ACTORSComma-separated username~actor pins, each registered as its own tool
BYTEWELLS_MAX_PASS_CENTSMaximum cents call-actor may auto-spend on a pass

Tools

ToolWhat it does
search-actorsSearch the Store (GET /v2/store)
fetch-actor-detailsListing README (trimmed), inputSchema, example input, pricing
call-actorStart a run, wait, return up to 100 dataset items + OUTPUT; may buy a pass
get-actor-runRun status and storage ids
get-dataset-itemsPage a dataset
get-key-value-store-recordRead a KV record (default OUTPUT)
abort-actor-runAbort a run
get-actor-passesQuote Flash / Burst / Sprint / Monthly
purchase-passBuy an explicit tier
list-my-listingsYour listings, prices in cents, and priceChangeAvailableAt
get-my-listingOne listing you own (id, slug, or actor name)
create-my-listingDraft listing for an Actor you own
update-my-listingUpdate copy or prices. Published prices change every 14 days
publish-my-listingPublish, or pass status: "UNLISTED" so the slug works but the Actor stays out of Store search and Google. The first publish starts the 14-day price lock
unpublish-my-listingTake the listing off the Store. Does not reset the lock
add-actorPin an Actor as tool bytewells--user--actor from its inputSchema

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 purchase

  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, 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. 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.

Manage your own listing

With the same API key, an agent can list, create, price, publish, and unpublish Actors you own. Prices on update-my-listing are integer cents (2900 is $29.00). Once a listing has been published, the monthly rental and Flash, Burst, and Sprint prices can change once every 14 days. A sooner change returns 409 price-change-too-soon and priceChangeAvailableAt. An admin sends overridePriceCooldown: true for a support correction.

Typical agent flow

  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.

On this page