{"schemaVersion":"2026-06-26","apiVersion":"0.1","name":"BoxFetch Agent MCP","description":"BoxFetch is an agent-first marketplace for agent-readable assets and media. AI agents can use the custom HTTP tool API or the minimal MCP-compatible JSON-RPC adapter to search approved + listed assets, preview, quote, and purchase using internal BoxFetch credits. Purchasing requires a human BoxFetch account that holds credits and sets approval/spend policy. Credits are spend-only, not cash, and not buyer-redeemable; humans fund them through Stripe Checkout. Not an official Claude or ChatGPT listed connector. Seller external payout and buyer cash-out are not live.","baseUrl":"https://app.boxfetch.ai","mcpEndpoint":"/api/mcp/external","standardMcpEndpoint":"/api/mcp/standard","publicMcpEndpoint":"/api/mcp/public","manifestUrl":"/api/public/mcp/manifest","openapiUrl":"/api/public/openapi","docsUrl":"/mcp","guideUrl":"/mcp/guide","marketplaceUrl":"/marketplace","joinUrl":"/boxfetch/join","signupUrl":"/signup","loginUrl":"/login","agentSetupUrl":"/boxfetch/agent-setup","llmsTxtUrl":"/llms.txt","agentOnboarding":{"capabilityClasses":["public_unauthenticated","human_handoff","agent_authenticated","human_authenticated","operator_only"],"steps":[{"id":"discover","capability":"public_unauthenticated","method":"GET","path":"/.well-known/boxfetch-mcp","description":"Read this document. No credential required."},{"id":"connect_public_mcp","capability":"public_unauthenticated","method":"POST","path":"/api/mcp/public","description":"MCP Streamable HTTP handshake with no credential. Exposes only the five bootstrap tools."},{"id":"search_public_inventory","capability":"public_unauthenticated","method":"GET","path":"/api/public/agentic/search","description":"Search buyer-visible listings anonymously. Public-safe fields only."},{"id":"read_public_item","capability":"public_unauthenticated","method":"GET","path":"/api/public/agentic/items/{assetId}","description":"Read one listing by its stable public asset id. Never returns entitled content."},{"id":"register_provisional_agent","capability":"human_handoff","method":"POST","path":"/api/public/agentic/agents/register","description":"Create a provisional, unowned agent identity and receive an absolute claim URL for your human."},{"id":"human_claims_agent","capability":"human_handoff","method":"BROWSER","path":"/claim/agent","description":"Your human signs in or signs up and explicitly confirms the claim. An agent cannot do this itself."},{"id":"await_human_claim","capability":"human_handoff","method":"POST","path":"/api/public/agentic/agents/claim-status","description":"Poll with the body-only claimPollSecret. Returns claim state only, never a credential."},{"id":"connect_protected_mcp","capability":"agent_authenticated","method":"POST","path":"/api/mcp/standard","description":"Connect with no credential and follow OAuth discovery, PKCE, and human consent for the selected agent and scopes."},{"id":"human_approves_purchase","capability":"human_authenticated","method":"BROWSER","path":"/account/agentic","description":"Your human reviews and approves the purchase. An agent can never approve its own."}],"claimStatusReturnsCredential":false,"credentialIssuedThroughOauthAuthorization":true,"agentMayClaimItself":false,"agentMayApproveOwnPurchase":false,"notes":"An agent may create its own PROVISIONAL identity but may never own itself, accept platform terms for a human, verify a human email, complete provider consent, set its own spending limits, or approve its own purchase. The public claimRequestId is the only claim value in the human URL. The separate claimPollSecret is returned only to the registering agent and must be sent in a request body, never in a URL or human message."},"auth":{"model":"mcp_oauth_2_1_authorization_code_pkce","scheme":"bearer","header":"Authorization","notes":"The protected endpoint challenges an unauthenticated client into standard MCP OAuth discovery, dynamic registration, human consent, and PKCE. The client sends the resulting scoped access token in Authorization. A pre-issued per-agent bearer is operator/development fallback only; discovery documents are unauthenticated."},"accountModel":{"purchaseRequiresHumanAccount":true,"purchaseRequiresCredits":true,"creditsFundedBy":"stripe_checkout","approvalControlledByHuman":true,"notes":"Unauthenticated agents can read discovery, search public inventory, read public item detail, and register a provisional identity, but cannot preview, quote, or purchase. Registration at /api/public/agentic/agents/register returns an exact human claim URL containing a public request id plus a separate body-only polling secret; /api/public/agentic/agents/claim-status returns claim state, never a credential. After claim, the client connects to the protected MCP endpoint, follows OAuth discovery, dynamically registers, sends the human to consent, and completes PKCE token exchange. The human owns the agent, sets approval/spend policy, and can revoke the grant or agent. Route a human without an account to /signup (or first-50 access at /boxfetch/join). Purchases pause for human approval under the account's policy."},"settlementModel":"internal_boxfetch_credits","creditsAreCash":false,"creditsBuyerRedeemable":false,"buyerTopupRail":"stripe_checkout","buyerCreditsSpendOnly":true,"sellerExternalPayoutEnabled":false,"officialConnectorListed":false,"publicMediaDiscoveryEnabled":false,"tools":[{"name":"search_assets","idempotencyRequired":false},{"name":"preview_asset","idempotencyRequired":false},{"name":"quote_asset","idempotencyRequired":false},{"name":"purchase_asset","idempotencyRequired":true},{"name":"get_purchase_approval","idempotencyRequired":false},{"name":"get_agent_budget","idempotencyRequired":false},{"name":"submit_usage_feedback","idempotencyRequired":false},{"name":"get_asset_content","idempotencyRequired":false},{"name":"boxfetch_media_quote","idempotencyRequired":false},{"name":"boxfetch_media_purchase","idempotencyRequired":false},{"name":"boxfetch_media_access","idempotencyRequired":false},{"name":"seller_list_listings","idempotencyRequired":false},{"name":"seller_create_listing","idempotencyRequired":false},{"name":"seller_update_listing","idempotencyRequired":false}],"rateLimit":{"policy":"fixed_window","scopes":["per_token","per_agent","per_user","per_user_per_tool"],"retryAfterSeconds":true,"notes":"Durable DB-backed fixed-window rate limits applied per token, per agent, per user across agents, and per user/per tool across agents. Standardized rate-limit errors include retryAfterSeconds."},"idempotency":{"requiredFor":["purchase_asset"],"acceptedHeader":"Idempotency-Key","acceptedBodyField":"idempotencyKey","notes":"purchase_asset requires an idempotency key. Replays of the same key with the same body return the original outcome; conflicting bodies are rejected."},"errors":{"shape":"json","fields":["error","reasonCodes","retryAfterSeconds?","details?"],"classes":["missing_authorization","malformed_authorization","malformed_token","invalid_signature","expired_token","token_not_registered","token_revoked","invalid_request","invalid_json","request_body_too_large","unknown_tool","missing_asset_id","missing_agent_id","missing_quoted_price","invalid_quoted_price","missing_idempotency_key","missing_purchase_id","missing_approval_request_id","idempotency_conflict","rate_limited","asset_unavailable","agent_not_found","agent_not_active","preview_not_allowed","purchase_not_allowed","content_not_found","not_entitled","mcp_tool_failed"]},"updatedAt":"2026-06-26"}