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
Hosted (recommended)
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)
| Variable | Purpose |
|---|---|
BYTEWELLS_TOKEN | API key (required for stdio) |
BYTEWELLS_API_URL | API base URL (default https://bytewells.com/api) |
BYTEWELLS_ACTORS | Comma-separated username~actor pins, each registered as its own tool |
BYTEWELLS_MAX_PASS_CENTS | Maximum cents call-actor may auto-spend on a pass |
Tools
| Tool | What it does |
|---|---|
search-actors | Search the Store (GET /v2/store) |
fetch-actor-details | Listing README (trimmed), inputSchema, example input, pricing |
call-actor | Start a run, wait, return up to 100 dataset items + OUTPUT; may buy a pass |
get-actor-run | Run status and storage ids |
get-dataset-items | Page a dataset |
get-key-value-store-record | Read a KV record (default OUTPUT) |
abort-actor-run | Abort a run |
get-actor-passes | Quote Flash / Burst / Sprint / Monthly |
purchase-pass | Buy an explicit tier |
list-my-listings | Your listings, prices in cents, and priceChangeAvailableAt |
get-my-listing | One listing you own (id, slug, or actor name) |
create-my-listing | Draft listing for an Actor you own |
update-my-listing | Update copy or prices. Published prices change every 14 days |
publish-my-listing | Publish, 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-listing | Take the listing off the Store. Does not reset the lock |
add-actor | Pin 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
- Agent calls
call-actor(or a pinned Actor tool). - If the API returns
402 rental-requiredwithdata.passes.nextUse, the serverGETs the pass offer. - If an active pass already covers now, it skips the buy and retries the run.
- Otherwise it
POSTs/v2/store/{user}/{actor}/passeswith{ tier, maxChargeCents }for the quoted tier, then retries the run once. - Set
purchasePass: falseoncall-actorto stop at the error/quote. SetBYTEWELLS_MAX_PASS_CENTSto 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
search-actorswith a query (for example"linkedin").fetch-actor-detailson the chosenactorRefand readinputSchema/exampleInput.call-actorwith valid input (andwaitSecsif you need results in one step).- If the run is still running,
get-actor-runthenget-dataset-items.