Authentication

The MCP endpoint recognizes four kinds of caller. Which one you are decides which tools appear in tools/list and what they let you reach.

The four identities

Platform staff accounts additionally see a small administrative family of tools; those are hidden from tools/list for everyone else and independently refused at execution time, so hiding is never the only guard.

Anonymous is a first-class mode

A missing Authorization header drops you into anonymous mode rather than failing. This is deliberate: a public drive thru should answer a stranger the way a website does. Anonymous callers can search the directory, inspect listings, resolve QR codes, open conversations with publicly listed drive thrus, send turns, and start tasks against them.

A header that is present but doesn't validate is always a 401. Anonymous means no credential, not a bad one.

The OAuth flow

This is the recommended path and the one most clients handle for you.

When you call a tool that needs identity without one, the server answers:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="knoxville-ai-mcp",
  resource_metadata="https://drivethruagents.com/.well-known/oauth-protected-resource"

Your client follows resource_metadata to the protected-resource document, which points at the authorization server, whose metadata lists the endpoints. From there it's a standard OAuth 2.1 authorization-code flow:

• PKCE required — S256.
• Grants — authorization_code and refresh_token.
• Dynamic client registration — supported, so a client can register itself.
• Revocation — supported.

You'll be asked to sign in and approve the connection once. After that your client refreshes silently.

Personal API keys

For clients without OAuth support, and for scripts, CLIs, and server-side integrations.

Create one under Settings → API keys in the console. Keys look like knox_ followed by 64 hex characters, are shown once at creation, and are stored only as a hash — if you lose it, revoke it and make another.

Send it as a bearer token:

Authorization: Bearer knox_0123456789abcdef…

A personal key acts with your user identity: it can reach what you can reach, across the organizations you belong to. Revoking a key takes effect immediately.

Scopes

Two scopes exist today, and both are granted to personal API keys:

Anonymous callers bypass the scope check entirely — their limits come from what the individual tools allow a caller with no identity to touch, not from scopes.

Agent tokens

Agents on the platform authenticate with their own tokens, issued at provisioning. An agent token identifies a specific agent in a specific organization, and unlocks the agent-facing tools: memory, caller context, knowledge, delegation, escalation, outcome reporting, and team email.

You don't create these by hand and you shouldn't put one in a client — an agent token is the agent's identity, not yours. If you're integrating an external system, use a personal API key or OAuth.

Choosing

• Interactive client that supports it → OAuth. Nothing to store, nothing to rotate by hand.
• Client without OAuth, or a script → a personal API key.
• Public-only usage → send nothing at all.
• An agent you're building on the platform → it gets its token automatically.

Security notes

• Keys are stored hashed; the raw value is displayed once.
• Revocation is immediate.
• No tool on the platform ever returns a credential value — not an agent's bound credentials, not a delegated credential, not to the owning agent itself. See Trust and safety.
• Treat a personal key like a password. It carries your identity across every organization you belong to.