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).
1. Discovery
Section titled “1. Discovery”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".
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:
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 |
2. Client identity
Section titled “2. Client identity”Pick one of these two ways to identify your client.
Dynamic client registration (RFC 7591)
Section titled “Dynamic client registration (RFC 7591)”Open registration, limited to 10 per minute per IP.
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;httponly onlocalhost,127.0.0.1or[::1]; or a private app scheme (cursor://…). Neverjavascript:,data:,file:or a fragment:400 invalid_redirect_uri.token_endpoint_auth_methoddefaults toclient_secret_basic. A confidential client also gets aclient_secret(mety_ocs_…), shown once.grant_typesmay only listauthorization_codeandrefresh_token;response_typesonlycode.- Registered clients that never connected are deleted after 30 days.
Client ID Metadata Document
Section titled “Client ID Metadata Document”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).
3. Authorization request (PKCE required)
Section titled “3. Authorization request (PKCE required)”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%2Fmcpcode_challengewithS256is required. The verifier is 43–128 unreserved characters.redirect_urimust exactly match a registered one (any port on a loopbackhttpredirect).scopeis 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, elseinvalid_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.
What the person sees
Section titled “What the person sees”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.
4. Token exchange
Section titled “4. Token exchange”Form-encoded. Public clients send client_id; confidential ones authenticate with HTTP Basic or client_secret
in the body (401 invalid_client otherwise).
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 asAuthorization: Bearertohttps://api.mety.ai/mcp.
5. Refresh (rotating)
Section titled “5. Refresh (rotating)”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_XXXXXXXXXXXXXXXXXXXXXXXXEvery 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.
6. Revocation (RFC 7009)
Section titled “6. Revocation (RFC 7009)”curl -s -X POST https://api.mety.ai/oauth/revoke \ -d token=mety_ort_XXXXXXXX -d client_id=mety_oc_XXXXXXXXXXXXXXXXXXXXXXXXThe 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.
Connections, agents and accounts
Section titled “Connections, agents and accounts”- 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 surfacemcp. 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.