Organization MCP endpoint reference
How the organization MCP endpoint authenticates callers, reaches connectors, and protects personal credentials.
Authentication
Two credential lanes reach the endpoint. A valid x-anyray-api-key or
Authorization: Bearer ark_... takes precedence for Connect-managed tools.
For a URL-only client, AuthKit issues an access token scoped to the exact gateway /mcp/org
audience. The gateway verifies the token and WorkOS organization. Billing requires activated SSO,
an active WorkOS connection, current membership, allowed domains, team mapping, and no revocation.
Only the verified WorkOS sub and org_id reach Billing. The token is never stored.
| Response | When |
|---|---|
401 | No credential, or a token that fails verification. Carries WWW-Authenticate. |
429 | Live identity resolution or pre-verification is throttled. Carries Retry-After. |
503 | Billing, WorkOS, or AuthKit key discovery is unavailable, or the organization endpoint is not ready. |
Anyray registers the authorization server and Resource Indicator. OAuth stays closed until the current public gateway URL is registered.
Readiness states
The console reports the most-blocking sign-in state first.
| State | Means | Whose move |
|---|---|---|
ready | Developers can sign in now. | Nobody |
issuer_not_configured | Sign-in is not enabled for this deployment. | Anyray |
sso_not_connected | No identity provider is connected. | You |
sso_not_activated | The provider is connected but nobody has signed in through it yet. | You |
gateway_url_missing | No public gateway address is recorded. | You |
gateway_url_invalid | The recorded address is not a public https URL. | You |
resource_not_registered | The gateway address awaits WorkOS registration. | Anyray |
unavailable | The readiness check could not reach Anyray. This is not evidence either way. | Nobody |
Read them from get
/admin/v1/policies/claude-desktop/connectors/readiness. The console shows Checking while this
request is in flight, Check failed when the request itself fails, and Upgrade needed when the
gateway predates this response shape. Those labels are console states, not oauth.state values.
The readiness GET calls neither Billing nor connector vendors. OAuth readiness is refreshed once
per minute for the process. Connector access comes from a process-local cache that expires after
about 10 minutes. A connector without a fresh access entry reports accessUnknown.
/admin/v1/policies/claude-desktop/connectors/readiness/refresh refreshes OAuth readiness and the
connector cache, with at most four connector probes in flight. It requires policies:write. The
console's Re-check button uses this action when the principal can write the policy; read-only
principals re-read instead. The 15-second poll only reads. Trusted private-host connectors remain
accessUnknown because the public probe cannot verify their access posture.
The response also reports the endpoint and what the gateway can expose at /mcp/org.
| Field | Means |
|---|---|
endpoint | The registered Resource Indicator, or the locally derived organization endpoint while registration is pending. |
connectors.served | Saved connector rows accepted by the relay parser. |
connectors.openToEveryone | Served connectors that answered the anonymous MCP probe. |
connectors.needsSignIn | Served connectors that require a personal OAuth grant. |
connectors.accessUnknown | Served connectors whose current access could not be proven. |
connectors.dropped | Total saved rows omitted from /mcp/org. This is counted from the raw saved rows. |
connectors.dropReasons[] | Counts grouped by code-owned reason. not_servable uses built_in, stdio, or malformed. refused uses blocked_host or duplicate_name. No URL is returned. |
connectors.oauth[].id | Connector identity. No connector URL is returned here. |
connectors.oauth[].adoption | Distinct users with a live personal grant. kind is count, fewerThan, or unavailable. A count value is zero or at least three; the fewerThan value is always three. |
Counts of one and two never leave the gateway. Both return kind: fewerThan with value: 3. Zero
stays exact, and unavailable stays distinct from zero. In multi-tenant mode, a deployment owner
without a resolved tenant receives unavailable; the gateway never widens the query across tenants.
Only grants bound to the connector's current origin count. A grant from a replaced origin, or a
legacy grant with no stored connector URL, does not count because the relay would refuse it.
Connector access
For tools/list, the gateway reads saved connector rows and asks each upstream for its tools.
Authless tools are organization-wide. OAuth tools require the caller's personal grant. Their names
begin anyray_oauth__<connector>__.
The gateway owns OAuth state, PKCE, client registration, refresh, and encrypted grants. Tokens and temporary authorization frames use a purpose-derived key. Revoking a seat removes that user's grants; failure also fails the seat revocation so the operator can retry.
Data boundary
| Data | Where it lives |
|---|---|
| Remote connector registrations | The deployment's Postgres, with the gateway's policy state |
| Personal connector OAuth tokens and in-flight authorization data | Gateway ciphertext in the same Postgres |
| Upstream tool catalogs and connector sessions | Gateway memory; not persisted |
| AuthKit tokens | Verified in memory, then discarded |
| Tool arguments, results, and upstream response bodies | Content. Relayed, never written |
Logs and timings contain fixed metadata only, never credentials or relayed content.
Limits
Identity checks are throttled. A limit returns 429 with Retry-After.
| Scope | Requests per minute | Concurrent checks |
|---|---|---|
| Source IP before JWT verification | 600 | 16 |
| Gateway before JWT verification | 1,200 | 64 |
| WorkOS subject | 60 | 4 |
| Source IP at the gateway | 240 | 8 |
| Customer gateway process | 300 | 12 |
| Deployment at Billing | 240 | 8 |
| Tenant at Billing | 300 | 12 |
| Billing process | 600 | 32 |
Concurrent config, JWKS, and metadata refreshes share one request. Billing gives the WorkOS lookup 1.6 seconds and one page. Duplicate memberships or more than 100 groups fail closed.
Constraints
- Personal grants cannot be shared with another user or team.
- Connector groups cannot vary by team.
/mcp/orgserves remotehttpandsseservers, not Desktop built-ins or local commands.
See the endpoint reference for the wire contract.