Skip to content

OAuth for MCP connectors

Mety is an OAuth 2.1 authorization server (issuer https://api.mety.ai) for one protected resource, https://api.mety.ai/mcp. This is what lets Claude.ai, Claude Desktop, ChatGPT and Grok connect with Connect → Allow. If you only want to use one of those apps, see connecting clients.

OAuth tokens are accepted only at /mcp. REST answers 401 INVALID_TOKEN to them: use an API key there. OpenID Connect (ID tokens), OAuth on REST and private_key_jwt are not available.

The OAuth endpoints live outside /api. They answer plain OAuth JSON ({ error, error_description } on failure, not the Mety envelope), and discovery, register, token and revoke allow CORS from any origin (no credentials).

An unauthenticated POST /mcp answers 401 with:

WWW-Authenticate: Bearer realm="mety", resource_metadata="https://api.mety.ai/.well-known/oauth-protected-resource/mcp"

A rejected token adds error="invalid_token".

Terminal window
curl -s https://api.mety.ai/.well-known/oauth-protected-resource/mcp
{
"resource": "https://api.mety.ai/mcp",
"authorization_servers": ["https://api.mety.ai"],
"scopes_supported": ["records:read", "records:write", "records:delete", "pipelines:manage", "fields:manage", "feedback:write", "audit:read"],
"bearer_methods_supported": ["header"],
"resource_name": "Mety CRM",
"resource_documentation": "https://api.mety.ai/llms.txt"
}

GET /.well-known/oauth-protected-resource (without /mcp) answers the same. Then the RFC 8414 metadata:

Terminal window
curl -s https://api.mety.ai/.well-known/oauth-authorization-server
Field Value
authorization_endpoint https://api.mety.ai/oauth/authorize
token_endpoint https://api.mety.ai/oauth/token
registration_endpoint https://api.mety.ai/oauth/register
revocation_endpoint https://api.mety.ai/oauth/revoke
response_types_supported ["code"]
grant_types_supported ["authorization_code", "refresh_token"]
code_challenge_methods_supported ["S256"]
token_endpoint_auth_methods_supported ["none", "client_secret_post", "client_secret_basic"]
client_id_metadata_document_supported true
authorization_response_iss_parameter_supported true

Pick one of these two ways to identify your client.

Open registration, limited to 10 per minute per IP.

Terminal window
curl -s -X POST https://api.mety.ai/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "My MCP Client",
"client_uri": "https://example.com",
"redirect_uris": ["https://example.com/oauth/callback"],
"token_endpoint_auth_method": "none"
}'
{
"client_id": "mety_oc_XXXXXXXXXXXXXXXXXXXXXXXX",
"client_id_issued_at": 1763200000,
"client_name": "My MCP Client",
"client_uri": "https://example.com",
"redirect_uris": ["https://example.com/oauth/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}
  • redirect_uris: 1 to 10. Allowed: https; http only on localhost, 127.0.0.1 or [::1]; or a private app scheme (cursor://…). Never javascript:, data:, file: or a fragment: 400 invalid_redirect_uri.
  • token_endpoint_auth_method defaults to client_secret_basic. A confidential client also gets a client_secret (mety_ocs_…), shown once.
  • grant_types may only list authorization_code and refresh_token; response_types only code.
  • Registered clients that never connected are deleted after 30 days.

Use an HTTPS URL as your client_id and serve this JSON there:

{
"client_id": "https://example.com/oauth/client.json",
"client_name": "My MCP Client",
"redirect_uris": ["https://example.com/oauth/callback"],
"token_endpoint_auth_method": "none"
}

client_id must equal the URL. Mety fetches it over HTTPS to a public address, with no redirects, a 5-second timeout and a 10 KB cap, and caches it for a day. Metadata-document clients are public (none).

Send the person’s browser to:

https://api.mety.ai/oauth/authorize
?response_type=code
&client_id=mety_oc_XXXXXXXXXXXXXXXXXXXXXXXX
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_challenge=<BASE64URL(SHA256(code_verifier))>
&code_challenge_method=S256
&state=<random>
&scope=records%3Aread%20records%3Awrite%20feedback%3Awrite
&resource=https%3A%2F%2Fapi.mety.ai%2Fmcp
  • code_challenge with S256 is required. The verifier is 43–128 unreserved characters.
  • redirect_uri must exactly match a registered one (any port on a loopback http redirect).
  • scope is space-separated Mety scopes. Unknown ones (openid, offline_access…) are dropped. Without any, the connection gets the default key scopes (records:read records:write feedback:write).
  • resource, if sent, must be the MCP resource, else invalid_target.

Mety redirects (302) to the consent screen at app.mety.ai/oauth/authorize, signing the person in first if needed. A bad client or redirect URI is shown there, never redirected to. Other errors come back to your redirect URI as ?error=…&error_description=…&state=…&iss=https://api.mety.ai.

The consent screen shows your client’s name, the domain it sends people back to, the scopes, and the person’s accounts. They tick one, several or all of the accounts where they are owner or admin and click Allow. records:read is always granted; they may untick the other scopes. On success you receive ?code=…&state=…&iss=https://api.mety.ai; on Deny, ?error=access_denied.

Form-encoded. Public clients send client_id; confidential ones authenticate with HTTP Basic or client_secret in the body (401 invalid_client otherwise).

Terminal window
curl -s -X POST https://api.mety.ai/oauth/token \
-d grant_type=authorization_code \
-d code=XXXXXXXX \
-d code_verifier=XXXXXXXX \
-d redirect_uri=https://example.com/oauth/callback \
-d client_id=mety_oc_XXXXXXXXXXXXXXXXXXXXXXXX \
-d resource=https://api.mety.ai/mcp
{
"access_token": "mety_oat_XXXXXXXX",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "mety_ort_XXXXXXXX",
"scope": "records:read records:write feedback:write"
}
  • Codes live 5 minutes and are single use. A replayed code revokes the connection and archives its agent.
  • Access tokens (mety_oat_…) last 1 hour. Send them as Authorization: Bearer to https://api.mety.ai/mcp.
Terminal window
curl -s -X POST https://api.mety.ai/oauth/token \
-d grant_type=refresh_token \
-d refresh_token=mety_ort_XXXXXXXX \
-d client_id=mety_oc_XXXXXXXXXXXXXXXXXXXXXXXX

Every refresh returns a new refresh token (90 days) and invalidates the old one. Store the new one before using the access token. Presenting a used refresh token again within 30 seconds (a client retry) is refused but harmless; presenting it later is treated as theft and revokes the whole connection.

An expired or revoked access token at /mcp gets 401 INVALID_TOKEN: refresh, or ask the person to connect again if the refresh fails with invalid_grant.

Terminal window
curl -s -X POST https://api.mety.ai/oauth/revoke \
-d token=mety_ort_XXXXXXXX -d client_id=mety_oc_XXXXXXXXXXXXXXXXXXXXXXXX

The client authenticates as at the token endpoint (401 invalid_client otherwise). Then the answer is always 200, also for an unknown token. A refresh token revokes every token of its connection; an access token revokes only itself.

  • There is one live connection per (client, person). It holds one grant per chosen account.
  • In each chosen account, the first Allow creates an agent named after your client, with the title via <person>. Its MCP writes are audited as that agent with surface mcp. Allowing again reuses it.
  • A new consent replaces the set of accounts: an account left out is disconnected (grant revoked, agent archived). Accounts the person joins later are never added on their own.
  • Archiving the agent in an account’s Settings → Agents removes only that account. With no account left, the tokens are refused.
  • Every MCP request re-checks the token, the grant, that the agent is active and that the person is still a member, and narrows the scopes to what the person’s current role allows.
  • With more than one account, MCP tool calls must pass accountId. See multi-account connections.

Only SHA-256 hashes of codes, tokens and client secrets are stored.