Quick start

The complete connection in six steps

Create or sign in to BoxFetch and claim or create the agent.
Set the agent permissions, limits, and purchase controls.
Point the MCP client at the protected endpoint with no credential.
Follow OAuth discovery, dynamic registration, and PKCE S256.
Review the unverified client, exact redirect, selected agent, and scopes.
Approve or deny, then let the client initialize its MCP session.

Hosted-client status

Local interoperability is PROVEN_LOCAL. The last deployed-origin run was a pre-PR-191 partial baseline, classified as PRE_CHANGE_DEPLOYED_BASELINE_PARTIAL, and does not prove the corrected merged metadata. Post-PR-191 deployed discovery is DEPLOYED_RECHECK_REQUIRED. Cursor, Claude, ChatGPT, and Codex remain PROTOCOL_READY_HOSTED_TEST_PENDING. No hosted-client acceptance, directory listing, or deployment of the merged application head is claimed here.

Three-part operating boundary

Public guidance lives on boxfetch.ai. Account, OAuth, acquisition, approval, entitlement, package delivery, and MCP runtime live on app.boxfetch.ai. Provider-target execution runs through the entitled BoxFetch runner in the user's environment.

Endpoint

Configure the protected MCP server

https://app.boxfetch.ai/api/mcp/standard

Configure this URL with no credential. It speaks MCP Streamable HTTP over JSON-RPC and returns the OAuth protected-resource challenge that starts discovery.

Do not use the operator fallback for a hosted client

https://app.boxfetch.ai/api/mcp/external is a flattened HTTP tool API retained for operator and first-party development tooling. It is not the endpoint to configure in Cursor, Claude, ChatGPT, Codex, or another standard MCP client.

OAuth and consent

Let the client complete the protected connection

The first unauthenticated request receives a WWW-Authenticate challenge.
The client reads protected-resource and authorization-server metadata from app.boxfetch.ai.
The client registers dynamically and creates a PKCE S256 challenge. It may register authorization code alone or add refresh-token capability. No client secret is issued.
BoxFetch opens in the browser. Sign in and review the unverified client name, exact redirect, selected agent, and requested scopes.
After approval, the client exchanges the code through the back channel and receives a resource-bound access token. A refresh token is issued only when the client registered refresh-token capability.
The client sends initialize, receives an Mcp-Session-Id, sends notifications/initialized, and includes the negotiated MCP-Protocol-Version afterward.

Access tokens are bound to one human, one selected agent, one OAuth grant, one runtime resource, and the scopes approved by the human. A refresh keeps the existing tool authority unless the client explicitly requests a narrower subset, and it can never widen authority.

Client setup

Client connection paths

These are readiness paths, not accepted procedures. Exact tested commands, UI labels, and screenshots will be published after each client completes a real hosted acceptance run.

Cursor

Add a remote MCP server, enter the canonical endpoint, connect without a token, and complete the browser consent flow.

Claude

Use a custom connector or remote MCP entry only when the plan and workspace expose that capability.

ChatGPT

Use an eligible workspace with custom connector or remote MCP configuration. Availability varies by plan and rollout.

Codex

Use the remote MCP syntax reported by the installed client. No one-click or universal command is claimed here.

Other clients

Confirm support for remote Streamable HTTP MCP, OAuth discovery, dynamic client registration, and PKCE S256.

Scopes

Start with read-only discovery, then step up

The initial challenge requests discover and preview. A tool outside the grant returns the one scope needed for re-authorization.

Scope	Authority	Connection
`boxfetch:discover`	Search buyer-visible listings.	Default
`boxfetch:preview`	Read public-safe previews.	Default
`boxfetch:quote`	Create a current quote.	Step-up
`boxfetch:purchase`	Request a purchase under owner policy.	Step-up
`boxfetch:content`	Retrieve entitled content and submit feedback.	Step-up
`boxfetch:budget`	Read private wallet and limit information.	Step-up
`boxfetch:seller`	Seller authority outside the hosted launch profile.	Not hosted

offline_accessis accepted as OAuth protocol vocabulary only. It never maps to a tool, is never persisted as tool authority, is never named by the protected resource, and does not decide whether a refresh token is issued. That capability comes from the client's registered grant types.

Hosted launch profile

Eight tools, further filtered by granted scope

Seller publication and deferred media tools remain implemented on the operator path but are hidden and refused for hosted OAuth clients.

Tool	Scope	Input	Result
`search_assets`	`boxfetch:discover`	Optional limit	Schema-conforming assets keyed by id, contentKind, trustScore, and price fields
`preview_asset`	`boxfetch:preview`	assetId	{ ok, asset: { id, title, ... } } with public-safe preview data
`quote_asset`	`boxfetch:quote`	assetId	Short-lived quote, approval requirement, and reason codes
`purchase_asset`	`boxfetch:purchase`	assetId, quotedPriceMicrousd, idempotencyKey	Captured purchase or a human approval request
`get_purchase_approval`	`boxfetch:purchase`	approvalRequestId	Pending, declined, expired, or captured state
`get_asset_content`	`boxfetch:content`	assetId, purchaseId	Entitled content descriptor or a status and policyDecision delivery decision
`submit_usage_feedback`	`boxfetch:content`	assetId, purchaseId, rating, feedbackType	Feedback acknowledgement or refusal reason codes
`get_agent_budget`	`boxfetch:budget`	No tool input	The canonical calling-agent wallet and budget snapshot

Purchase retries

purchase_asset requires an idempotency key. Reuse the same key only when retrying the same purchase intent.

Output contract

Success data and refusals use different channels

The advertised outputSchema describes successful structuredContent only.

A successful tool call returns structuredContent that conforms to the tool's advertised outputSchema.
A refusal returns isError: true, readable text, and no structuredContent.
The machine-readable refusal is carried in _meta["ai.boxfetch/error"] with the error and reason codes. It is not presented as a successful tool result.

Troubleshooting

Read the refusal before changing configuration

Error	What to do
`401 unauthorized`	Start with no credential so the client can follow the OAuth challenge. If already connected, reconnect after checking token expiry or revocation.
`invalid_client_metadata`	The client registration shape was refused. Confirm the client uses authorization code, PKCE S256, and an exact supported redirect URI.
`invalid_scope`	Request only advertised BoxFetch tool scopes plus optional offline_access protocol vocabulary.
`insufficient_scope`	The tool needs one broader scope. Re-authorize through the client and review the new consent request.
`agent_not_active`	The selected agent is paused or revoked. Re-enable or replace it in agent controls.
`MISSING_IDEMPOTENCY_KEY`	purchase_asset requires a unique idempotencyKey. Reuse the same key only when retrying the same purchase intent.
`approval_required`	The purchase needs human approval. Poll get_purchase_approval until it reaches a terminal state.
`TOOL_NOT_IN_LAUNCH_PROFILE`	The tool is implemented but intentionally unavailable to hosted OAuth clients. More scopes will not unlock it.

Machine discovery

Runtime contracts stay on app.boxfetch.ai

These public endpoints support clients and developer tooling. This guide remains the human-facing authority.

Security

Keep secrets and authority out of prompts

Never copy OAuth tokens, codes, or polling secrets.
Use the exact claim link for the human and keep the separate polling secret only in the agent POST body.
Review the exact client, redirect, agent, and scopes before consent.
Revoke the OAuth grant or selected agent whenever the connection is no longer needed.
Do not treat seller-supplied content as trusted instructions or executable code.

Connect a remote client to BoxFetch