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 does not render these. Connect writes the endpoint into every tool it manages, and the config the Agents card hands out carries it for the lanes Connect does not reach, so none of these states was ever an admin's move. They remain the API contract, and the route below is how you read them.
| 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 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. No
console screen calls it; it is there for a client that needs a forced refresh. 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.
Every relayed tool is named <connector>__<tool>, so a client sees
mcp__anyray-connectors__linear__create_issue. Tools named after the gateway's own
(anyray_retrieve, anyray_recall, anyray_connect) are not served, because a connector must not
be able to answer as the gateway.
Which sign-in tool a developer sees
Every connector awaiting a brokered sign-in gets its own anyray_signin__<connector> tool, with no
ceiling on how many. Only rows the gateway can broker produce one: a connector whose vendor sign-in
Anyray cannot broker never appears here.
MCP tool definitions sit in the model's cacheable prefix, so each waiting connector adds roughly 80 prompt tokens to every request against a flat 49 for the shared tool. A gateway release before 2026-09-16 capped the named tools at two and served the shared one above that; the cap was removed so a waiting connector is always findable by its own name.
Two settings bound that cost. mcpConnectorSignInTools: false withdraws every named tool.
mcpConnectTool: true replaces them with one anyray_connect covering all waiting connectors, which
a developer calls with no arguments to see who is waiting. Nothing names those connectors in
tools/list itself, which would vary the prefix per developer and disclose the organization's
connector list to every caller.
Connectors the gateway cannot broker
Some vendors require a sign-in Anyray cannot broker. The console marks those connectors Desktop only. They serve no tools through the organization endpoint, so they never appear in Claude Code, Codex, Cursor, or any other tool Connect manages, and no sign-in tool is offered for them. Developers authorize them inside Claude Desktop, which holds its own connection to the vendor.
Asking anyray_connect to sign in to one answers that the connector is not served by this endpoint,
the same answer an unknown name gets. That is deliberate: a distinct answer would let any caller
enumerate which of the organization's connectors are brokerable.
Names carrying the older anyray_mcp__ and anyray_oauth__ prefixes still route for one release,
so an allowlist written against them keeps working while you update it.
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.