Skip to main content
Everything the wizard does, step by step. You’ll create your account with the admin CLI, register an OAuth client, and implement the “Connect with Agentcard” flow for your users.

​
1. Create your account

Install the admin CLI and log in — your account is created on first login, verified by magic link: 
npm install -g agent-cards-admin
agent-cards-admin login
Then create an organization (your OAuth clients live under it): 
agent-cards-admin orgs create

​
2. Create an OAuth client

agent-cards-admin oauth-clients create \
  --org <your-org-id> \
  --name "My App" \
  --redirect-uri "https://myapp.example.com/callback"
This returns your client ID and a client secret (starts with acs_, shown once). Pin both in your app’s environment, server-side only: 
AGENTCARD_OAUTH_CLIENT_ID=<client_id>
AGENTCARD_OAUTH_CLIENT_SECRET=<client_secret>
The --name is what users see on the consent screen. The client is created in your CLI’s current mode: sandbox (the default — its users get test cards) or production (live cards, requires an active subscription). Switch with agent-cards-admin env production before creating a production client. See Production.
Building a mobile app, SPA, or distributed CLI that can’t keep a secret? Add --public for a PKCE-only client with no secret. PKCE is enforced for every client either way.

​
3. Implement OAuth for your users

Your app needs three small pieces — the full flow, with a diagram and every request, is on the OAuth page:
  1. A connect route — when a user hits “Connect with Agentcard”, generate a PKCE verifier + state, store them for that user, and redirect to Agentcard’s /authorize.
  2. A callback route — Agentcard redirects back with a code; exchange it (plus the verifier and your client secret) at /token and store the tokens keyed to your user. This route must be publicly reachable — use a tunnel in local dev.
  3. Token refresh — when a call returns 401, refresh once and retry. Each refresh rotates the refresh token, so persist the new one.

​
4. Make authenticated requests

Call the MCP server with each user’s access token and expose the tools it advertises to your agent: 
POST https://mcp.agentcard.sh/mcp
Authorization: Bearer <access_token>
Register every tool tools/list returns dynamically rather than hardcoding names — tools Agentcard adds later then work with zero code change. Details in the MCP overview.

​
5. Verify in sandbox

Ask your agent to create a card for a connected test user, then confirm it independently with list_cards. A brand-new client seeing zero pre-existing cards is expected — connections only see the cards they created. When you’re ready to go live, agent-cards-admin subscribe activates your org and mints production keys.