BoxFetch MCP

Let your AI agent browse and buy approved boxes inside BoxFetch.

Connect an MCP-capable AI client and let it preview, quote, buy inside your limits, pause big-ticket buys for your approval, and retrieve purchased content. Purchases spend internal BoxFetch credits that you fund and control.

Who this is for

AI agents

Long-running assistants that should buy reviewed data with permission, not just summarise it.

MCP-capable clients

Claude, ChatGPT, custom workflows, and developer tools that support remote MCP servers or custom connectors.

Agentic-commerce builders

Teams experimenting with how to buy, sell, and approve on behalf of users without giving up control.

How it works

Connect your MCP client

Point the client at BoxFetch’s protected MCP endpoint with no credential.

Approve OAuth access

Follow discovery and PKCE, then let the human choose the agent and exact scopes on the BoxFetch consent page.

Search discoverable listings

Trust Works routing and moderation gates decide which seller listings are visible to buyers and external agents.

Preview and quote

Agents see preview text plus seller-declared content kind, size, and SHA-256 — never full content.

Buy within limits

Internal-credit capture on a fresh quote. Above the threshold the buy pauses for human approval.

Retrieve purchased content

After a captured purchase, get_asset_content returns Markdown text or safe container metadata; R2-backed content is delivered through a BoxFetch access grant, never a provider URL.

What agents can buy

Markdown reports

First-class native content. After purchase, agents receive normalized Markdown text. Up to 5 MB.

Seller-defined content containers

PDFs, ZIPs, images, datasets, template bundles, theme packs, font packs — anything the seller declares, up to 5 MB. After purchase, agents receive base64 bytes plus metadata.

BoxFetch does not parse, unzip, execute, render, or scan container bytes in this MVP. Treat seller-declared containers as untrusted files.

Safety model

Only approved + listed assets are visible to buyers and external agents.
Preview always comes before purchase — agents never see full content first.
Purchases above the user-set threshold pause for human approval.
Full content requires a captured purchase. Pending approvals do not unlock it.
External get_asset_content checks both purchaseId and the calling agent.
Tokens are scoped per agent and revocable from the issuing panel.
Internal BoxFetch credits only. Funded by Stripe Checkout; credits are spend-only, not cash, and not buyer-redeemable. Seller external payout and buyer cash-out are not live.

Tool sequence

The happy-path order an external agent calls. Above the user-set threshold, purchase_asset returns approvalRequired and the agent polls get_purchase_approval until the human captures or declines.

1search_assets
List discoverable listings.
2preview_asset
Buyer-safe preview + metadata. No full content. No seller usage instructions.
3quote_asset
Short-lived dynamic price quote.
4purchase_asset
Settle internal BoxFetch credits (Idempotency-Key required) — or get approvalRequired.
5get_asset_content
After captured purchase, retrieve Markdown text or safe container metadata.

Human approval branch

When purchase_asset returns approvalRequired with an approvalRequestId, the agent polls get_purchase_approval until status is captured, declined, or expired. Internal BoxFetch credits move only on captured.

Entitlement rule

Full content is only available via get_asset_content after a captured purchase or approved capture. Preview and search never expose private content, seller usage instructions, or internal Trust Works details.

Tool reference

Eight MCP tools cover the full agentic loop. Detailed inputs, outputs, and examples are in thesetup guide.

search_assets

List approved + listed marketplace assets.

preview_asset

Buyer-safe preview with metadata only — no full content.

quote_asset

Short-lived dynamic price quote.

purchase_asset

Settle internal BoxFetch credits against a quoted price. Requires idempotencyKey externally.

get_purchase_approval

Poll a human approval request from purchase_asset.

get_asset_content

After captured purchase, retrieve Markdown text or base64 container bytes.

submit_usage_feedback

Record validated usage feedback for a captured purchase.

get_agent_budget

Read the calling agent’s wallet/budget snapshot.

Connector status

Use BoxFetch’s MCP endpoint with AI clients that support remote MCP servers or custom connectors. Availability and setup screens vary by AI product and plan.

BoxFetch is not yet a listed or official connectorinside Claude or ChatGPT. There is no automatic discovery. For now, use the guide below with your own BoxFetch account and an external MCP token you generate from Account → Agentic.

MCP endpoints

POST /api/mcp/external

Existing custom HTTP tool API used by the SDK-lite examples. Primary shape is { toolName, ...input }. Also accepts { tool, input }.

POST /api/mcp/standard

Protected MCP Streamable HTTP JSON-RPC endpoint. Supports initialize, notifications/*, tools/list, and tools/call. Protocol revisions 2025-11-25 and 2025-06-18 are negotiated at initialize. Authorization is standard MCP OAuth 2.1: connect with no credential and your client follows the WWW-Authenticate challenge through RFC 9728 resource metadata to an authorization-code + PKCE flow your human approves. Initialize returns a durable session, notifications/initialized activates it, DELETE releases it, and GET remains 405 because no server-initiated SSE stream exists.

POST /api/mcp/public

Cold start. No credential required. An MCP client with no BoxFetch token can complete a handshake here and call five public tools: boxfetch_discover, boxfetch_search_public, boxfetch_get_public_item, boxfetch_register_agent, and boxfetch_check_claim_status. Nothing that purchases or returns entitled content is reachable on this endpoint.

Developer quickstart

Six steps to wire an agent. Purchases settle in internal BoxFetch credits. Seller external payout and buyer cash-out are not live.

1. Discover — fetch /llms.txt and /.well-known/boxfetch-mcp.
2. Inspect — /api/public/openapi and /api/public/mcp/manifest.
3. Connect — point the MCP client at /api/mcp/standard with no credential and complete OAuth discovery, human consent, and PKCE.
4. Test — run pnpm mcp:smoke for a section-headed PASS / WARN / FAIL report (discovery + live loop).
5. Build — copy the TypeScript or Python SDK-lite example (single file, no install).
6. Safety — internal BoxFetch credits only. Honor the approval threshold and spending limits.

Discovery & developer references

Public, unauthenticated. Manual configuration required — BoxFetch is not a listed or official Claude or ChatGPT connector today.

/llms.txt — plain-text discovery file.
/.well-known/boxfetch-mcp — JSON discovery document.
/api/public/mcp/manifest — connector manifest with tool JSON schemas.
/api/public/openapi — OpenAPI 3.1 contract.

Ready to connect your AI agent?

Read the setup guide, browse the public marketplace, or create an account to generate an external MCP token. Purchases settle in internal BoxFetch credits.

Open the setup guide Browse marketplace Create account