Organization MCP hub

Add connectors once, then reach them through https://<gateway>/mcp/org from any MCP client.

Authless connectors relay through the in-deployment MCP hub. Connectors that need their own OAuth grant relay from the gateway as the calling developer. The gateway accepts either the developer's existing ark_ client key or an AuthKit access token from the organization's WorkOS SSO connection.

Set it up

1

Bring up the hub

In .env, set ANYRAY_MCP_HUB_URL=http://mcp-hub:4444 and ANYRAY_MCP_HUB_ENCRYPTION_SECRET to 32 or more random characters. setup.sh mints the secret. Start the stack with docker compose --profile mcp-hub up -d.

The hub signs and verifies its internal tokens with ANYRAY_ADMIN_TOKEN, which the gateway already holds. There is no second shared signing secret.

2

Add connectors in the console

Open Settings → Connectors and choose Add connector. The catalog carries Claude's public connector directory: browse it, narrow it by category, or search by name. Some of those connectors are served by Claude itself and have no address of their own, so searching for one says that rather than coming back empty. Paste a server's address for anything not listed. Anyray asks the server for its name and tool list first: a server that answers openly is hosted by the hub. A connector that says "sign-in required" is OAuth. Each developer authorizes it for themselves in the next step. Remote connectors (an http or sse URL) are supported. Desktop built-ins and stdio commands stay Desktop-only: the first are app plumbing, the second need a machine to run on. The relay panel shows the hub's status, remote connector count, shared authless tool count, and relay p95. Open Latency and outcome details for the process-local sample count, p50, p95, and last fixed outcome class for each leg. The samples reset when this gateway replica restarts.

3

Connect organization SSO

Follow Enterprise SSO enrollment if the organization has not connected its identity provider yet. Choosing Set up SSO is the explicit opt-in that creates the WorkOS organization; MCP readiness never creates one for an ordinary tenant. The same WorkOS organization controls MCP sign-in. MCP OAuth stays closed until a vendor operator confirms that its organization policy requires SSO.

4

Authorize personal connectors

Each developer authorizes every connector that needs access to their account:

npx anyray-connect connectors authorize "Atlassian"

The command opens the vendor consent page and prints the account that received the grant. Over SSH, run it again with the claim code: --claim <code>. The console's Authorize action starts the same personal flow. It never creates an organization-wide grant.

5

Add the organization endpoint

In a URL-based MCP client, add:

https://gateway.example.com/mcp/org

Do not add a custom header. The client discovers WorkOS AuthKit and asks the developer to sign in with the organization's existing SSO. Connect-managed tools need no manual step. Connect writes the same URL with the developer's ark_ key.

Verify OAuth discovery

curl -s https://gateway.example.com/.well-known/oauth-protected-resource | jq

The response names https://gateway.example.com/mcp/org as resource and the WorkOS AuthKit origin under authorization_servers. Calling /mcp/org without credentials returns 401 with a WWW-Authenticate header that points back to this metadata.

Authentication

The client-key lane stays available for every Connect-managed tool. A valid x-anyray-api-key or Authorization: Bearer ark_... takes precedence.

For a URL-only client, AuthKit issues an access token for the exact gateway /mcp/org audience. The gateway verifies its signature, issuer, audience, expiry, subject, and WorkOS organization. Billing then requires the tenant's activated SSO marker and a currently active WorkOS connection. It checks the current WorkOS user, active organization membership, groups, allowed domains, team mapping, and Anyray revocation state. A disconnected IdP or user removed from the organization is denied on the next request.

The gateway sends only the verified WorkOS sub and org_id to Billing. The AuthKit access token is never forwarded or stored. OAuth-authenticated access returns 429 with Retry-After when live identity resolution or pre-verification work is throttled, and 503 when Billing, WorkOS, or AuthKit key discovery is unavailable. It also returns 503 until a vendor operator confirms this gateway's exact Resource Indicator and the organization's SSO policy.

Connector OAuth grants

tools/list merges authless hub tools with the connectors the caller has personally authorized. OAuth tool names begin anyray_oauth__<connector>__. A developer without a grant does not see those tools. Calling one returns Authorize this connector before calling its tools.

Anyray encrypts upstream access tokens, refresh tokens, and temporary PKCE verifiers with a dedicated key derived from the deployment content key. Tokens never appear in policy exports, logs, or tool results. Revoking a seat removes that user's connector grants. A failed removal makes seat revocation fail so an operator can retry it.

Existing hub-held grants remain for their legacy lifecycle record, but OAuth tools are not exposed through the public hub server. A developer who authorizes the same connector gets a separate personal grant.

Retry a failed sync

Open Settings → Connectors. Review the remote connector addresses and sign-in state, then choose Retry sync. Choose Sync now when you want to refresh the mirror before the five-minute interval. Both actions wait for one round and return only counts, timings, and fixed outcome classes. If no counts appear, the round failed before the hub returned a summary. Check the hub service health and retry.

Data boundary

Authless connector registrations and tool catalogs live on the hub volume. Personal connector OAuth tokens live only as gateway ciphertext in the spend ledger. AuthKit tokens are verified in memory and discarded. Tool arguments, results, and upstream response bodies are content and are never written.

The hub runs with DB_METRICS_RECORDING_ENABLED=false, so it does not store a failed call's raw upstream error body. The gateway logs error class names only.

Limits

• A personal connector grant cannot be shared with another user or team.

• Per-team connector groups are not available. Authless hub connectors remain organization-wide.

• Without ANYRAY_MCP_HUB_URL, authless tools are unavailable. A caller with a personal connector grant can still use that connector through /mcp/org.

• OAuth identity checks use these per-process limits. A 429 response includes 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 authorization-metadata refreshes share one in-flight request. Billing gives the complete WorkOS lookup 1.6 seconds, disables SDK retries, and reads at most one page: two matching memberships or 100 groups. A next page fails closed. Connection discovery reads at most five 100-row pages and stops at the first active connection. Hitting that bound returns 503, not a false denial.

• Older MCP clients may need Dynamic Client Registration enabled in the managed WorkOS environment.

The WorkOS authorization-server setup and exact Resource Indicator registration are managed by Anyray. A new public gateway URL reopens that task and keeps OAuth closed until the new URL is registered. See the endpoint reference for the wire contract.