Sign in
MCP / MCP Client Setup

MCP Client Setup

Instead of configuring the client manually, copy this prompt into your AI agent. The agent will read the installation instructions and add the Giftronaut MCP server to its own MCP configuration.

The install prompt

Copy this verbatim into Claude Desktop, Cursor, ChatGPT (with file connectors), or your custom agent:

Prompt
Please install yourself as a Giftronaut MCP client.

Read the following file and follow its Standard auto-flow exactly:
https://api.giftronaut.com/docs/md/mcp/agent-install.md

Server URL: https://api.giftronaut.com/api/v1/mcp
Add it to your MCP client config (no Authorization header — OAuth is automatic),
then make any tool call to trigger the browser sign-in.
The agent fetches the canonical Markdown source, reads it like an SOP, and self-configures. Because agent-install.md is shipped as a public, machine-readable file, the instructions stay versioned with the server. This helps prevent the agent from following outdated setup instructions.

What the agent does

  1. Writes the server URL to its MCP client config (path varies per client; agent-install.md lists Claude Desktop, Cursor, OpenCode, MCP Inspector).
  2. Issues a tool call. The server responds 401 with a WWW-Authenticate: Bearer realm="https://api.giftronaut.com/api/v1/mcp", resource_metadata="..." header.
  3. The SDK fetches /.well-known/oauth-protected-resource (RFC 9728) and discovers our authorization server.
  4. Registers itself dynamically via POST /oauth2/register (RFC 7591). No human pre-provisions the client.
  5. Opens the user's default browser to /oauth2/authorize with PKCE S256.
  6. After portal sign-in + OTP (or Google OAuth2), the user picks which AppClient to act as.
  7. Exchanges the code at /oauth2/token with resource=https://api.giftronaut.com/api/v1/mcp — RFC 8707 audience binding adds aud=["https://api.giftronaut.com/api/v1/mcp"] to the JWT (matches PRM resource field exactly).
  8. Caches the token set in the client's MCP auth store (e.g. ~/.local/share/opencode/mcp-auth.json).

What's in the resulting token

ClaimMeaning
client_idYour registered MCP client (DCR identity).
acting_as_app_client_idThe user's chosen Giftronaut AppClient — drives org_id + env.
org_id, owner_id, owner_email, envDerived from the chosen AppClient.
scopeIntersection of (DCR-requested ∩ AppClient-allowed) scopes.
aud["https://api.giftronaut.com/api/v1/mcp"] — required for the MCP endpoint to accept the token (RFC 9728 canonical URI, matches PRM resource).

Can I use client_credentials for MCP?

No. MCP requires a browser-based sign-in so it can identify the user behind each request. Tokens created with client_credentials do not include that user identity, so MCP will reject them with a 401 invalid_token error. You can still use your existing client_credentials tokens with the REST API, including endpoints such as /api/v1/orders and /api/v1/balance.