MCP Authentication#

The GekkoVet MCP server accepts two authentication flows:

  1. Interactive user authentication — OAuth 2.0 authorization code flow. A real GekkoVet user signs in through the AWS Cognito Hosted UI, and the MCP client receives an opaque access token. This is the default path used by MCP-compatible clients such as Claude Desktop, ChatGPT, and the MCP Inspector.
  2. Machine-to-machine (M2M) authentication — OAuth 2.0 client credentials grant, using the same token endpoint as the GekkoVet REST API (https://authentication.gekkovet.com/oauth2/token). Suitable for backend services and automations that act without a human in the loop.

Pick the flow that matches your integration. Both produce a bearer token you attach to /mcp requests as Authorization: Bearer <token>.

Interactive user authentication#

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.

Machine-to-machine authentication#

Backend services can authenticate against the MCP server using the same client credentials flow documented for the GekkoVet REST API. The MCP server validates tokens issued by https://authentication.gekkovet.com/oauth2/token directly — there is no separate token endpoint or registration step for M2M on the MCP side.

Prerequisites#

  1. Contact GekkoVet to obtain CLIENT_ID / CLIENT_SECRET — the same credentials used for the REST API. An M2M integration must be provisioned as a machine veterinarian on the GekkoVet side so tool calls have a valid user identity.
  2. Agree on scopes. M2M tokens are issued with the scopes granted to your credentials (for example gekkovet/tools). Discuss with your GekkoVet contact which scopes your integration needs.

Flow overview#

  1. Token request. POST to https://authentication.gekkovet.com/oauth2/token with grant_type=client_credentials and HTTP Basic authentication using your CLIENT_ID:CLIENT_SECRET. Cognito returns a signed JWT access token.
  2. Tool calls. Send the JWT directly to https://mcp.gekkovet.workers.dev/mcp as Authorization: Bearer <access_token>. The MCP server validates the signature against GekkoVet’s identity provider, resolves the machine user, and dispatches to the tool. No browser redirect, no dynamic registration, no refresh-token dance.

Example#

Obtain a token:

curl -X POST https://authentication.gekkovet.com/oauth2/token \
  -H "Authorization: Basic $(echo -n "CLIENT_ID:CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=gekkovet/tools"

Call a tool:

JWT="<access_token from above>"
curl -X POST https://mcp.gekkovet.workers.dev/mcp \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,"params":{"name":"list_animal_types","arguments":{}}}'

Tokens from authentication.gekkovet.com expire after one hour (expires_in: 3600). Request a new one when needed — there is no refresh token for the client credentials grant.

Identity propagation#

M2M tokens carry your client_id in the sub claim. On the GekkoVet side that client_id is mapped to a dedicated machine veterinarian account; subsequent tool calls are scoped to that account’s data just as they would be for a human user. Invoke the whoami tool to confirm the identity the server sees.

Subscription gating does not apply to M2M tokens — access is governed entirely by the scopes attached to your credentials.

Revoking access#

Revoking access is not yet exposed directly in the MCP server. To disconnect an interactive client, clear the saved MCP configuration in your AI assistant. For M2M credentials, contact us to rotate or retire the CLIENT_ID/CLIENT_SECRET. 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.
  • M2M token rejected as 401 invalid_token. Confirm the token came from https://authentication.gekkovet.com/oauth2/token, hasn’t expired, and that your CLIENT_ID has been registered as a machine veterinarian with GekkoVet.
Backward Connecting an AI Assistant Tool Reference Forward