MCP Authentication#

Unlike the GekkoVet REST API (which uses the client credentials grant), the MCP server authenticates end-users interactively using the OAuth 2.0 authorization code flow. This means every MCP tool call runs on behalf of a real GekkoVet user account — the same account you use to log into GekkoVet itself.

The AI assistant never sees your GekkoVet password. It only ever holds an opaque access token issued by the MCP server.

Flow overview#

1. Discovery. The client fetches https://mcp.gekkovet.workers.dev/.well-known/oauth-authorization-server and learns the authorize, token, and registration endpoints.
2. Dynamic client registration. The client registers itself via POST /register (RFC 7591) and receives its own client_id and client_secret. You do not need to pre-provision credentials.
3. Authorization redirect. The client opens /authorize in the user’s browser with PKCE parameters. The MCP server redirects to the GekkoVet login page (AWS Cognito Hosted UI).
4. User login. The user signs in with their GekkoVet credentials. Cognito issues an authorization code to the MCP server’s /callback.
5. Token exchange. The MCP server wraps the Cognito session in its own OAuth token and returns it to the client via /token.
6. Authenticated tool calls. The client includes Authorization: Bearer <access_token> on every request to /mcp. Tokens refresh automatically.

Discovery endpoint#

curl https://mcp.gekkovet.workers.dev/.well-known/oauth-authorization-server

{
  "issuer": "https://mcp.gekkovet.workers.dev",
  "authorization_endpoint": "https://mcp.gekkovet.workers.dev/authorize",
  "token_endpoint": "https://mcp.gekkovet.workers.dev/token",
  "registration_endpoint": "https://mcp.gekkovet.workers.dev/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "code_challenge_methods_supported": ["plain", "S256"]
}

MCP-compatible clients consume this metadata automatically — you don’t normally need to call it yourself.

Scopes#

The Cognito app client requests the standard OIDC scopes: openid, email, profile. The MCP server uses these to extract your veterinarian ID, email, and name so tools can act on your behalf. You can confirm what the server sees about you by invoking the whoami tool from any MCP client.

Revoking access#

Revoking access is not yet exposed directly in the MCP server. To disconnect a client, clear the saved MCP configuration in your AI assistant. If you need a Cognito session invalidated, contact us — we’ll revoke the refresh token on the server side.

When OAuth fails#

If the first connection loops back to the login page or returns an error, the most common causes are:

• Callback mismatch. Only https://mcp.gekkovet.workers.dev/callback is whitelisted on the Cognito app client. If you’re running a local/forked MCP server, register a separate callback URL with us.
• Browser blocked the popup. Some clients open the authorize URL in a popup — if it was blocked, retry the connect flow.
• Stale tokens. Delete the cached client registration (typically under ~/.mcp-remote-auth/ or similar for mcp-remote) and try again.