MCP gateway

MCP in both directions: clients reaching xpander, and agents reaching skills served over MCP, including your own MCP gateway.

Clients such as Claude, ChatGPT and Cursor reach xpander over MCP. Agents reach skills that are served over MCP, with the same approvals, credentials and record as any other skill.

Inbound: clients reach xpander over MCP

The api service is the entry point. REST calls carry an API key. MCP takes OAuth 2.1 only, on every deployment.

Endpoint	Auth	What it exposes
https://api.xpander.ai/mcp/ (self-hosted: https://api.<your domain>/mcp/)	OAuth 2.1	The xpander API itself: agents, tasks and threads, skills and operations, custom functions, workspace files, schedules, usage. Each operation is one API call. It is not an agent. Setup: Model Context Protocol
https://omni.xpander.ai/mcp (self-hosted: /omni-mcp/)	OAuth 2.1 in the browser	Omni: task the organization’s agents, build skills and agents from what admins approved, start cloud sessions, ask what a run did. Setup: Connect your MCP client

How a client signs in

1. A call without a token gets 401 with WWW-Authenticate: Bearer resource_metadata=.../.well-known/oauth-protected-resource. An x-api-key header gets the same 401.
2. The client registers at /oauth/register.
3. The person signs in at /oauth/authorize with PKCE, and the client exchanges the code at /oauth/token.
4. The client calls /mcp/ with Authorization: Bearer <token>.

On an Air-Gapped install

The Omni endpoint is the install’s public MCP URL, global.mcp.publicUrl. Until it is set, /omni-mcp/ answers 404, the MCP row on Platform > Agents > Channels reads Not offered on this install, and the License page shows MCP endpoint as Disabled. An agent’s Channels pane shows only Omni and API, so the organization switch decides. See Channels.

The Skills registry address

Platform > Agents > Skills registry gives MCP clients one address for the organization’s registry. Each person signs in as themselves.

Install	Address
Air-Gapped	The public API address followed by /mcp, from global.apiPublicUrl, else the API host (global.hosts.api or api.<global.domain>). A host set only on the API’s own ingress does not count. With neither, the page says The gateway is not available on this install yet. Ask your admin to set its public API address.
Hybrid	Nothing to set. If the page shows that message, contact xpander support.

Each person’s library, in preview

Each person’s own library is served as one MCP endpoint at your MCP host: mcp.<your domain> on Hybrid (from the chart’s ingress, no global.mcp value). Air-Gapped has no MCP host, so it is not served there.

Per-agent MCP URLs are no longer served. Hybrid clients move to the MCP host. Air-Gapped clients move to https://api.<your domain>/mcp/, which lists and runs your agents.

The APP_URL value

/oauth/authorize redirects to ${APP_URL}/oauth_login, read from the api service, so APP_URL must be the UI origin. On the API host, the browser lands on {"detail":"Not Found"}. Chart keys: Model Context Protocol.

Outbound: skills served over MCP

Settings > Skills > MCP servers with Add server. Shown with sample data.

Every place below takes the same fields: Name, Server type (Remote or Local), Server URL, Transport (HTTP or SSE), Authentication (None, API key, OAuth2, Headers or Signed-in user (SSO)), and an optional Health check. For Signed-in user (SSO), Token sent is Access token, ID token or Exchange for an audience (with an Audience).

Where to register an endpoint

Where	Who it is for
Settings > Skills > MCP servers tab > Add server	Any member. Shared with Private or Organization
Agent settings > Skills > Add skill > Custom skill > MCP Connector	An agent’s owner. Add to organization registry makes it a shared entry. See Add a skill
Platform > Agents > Skills registry > Add item > MCP server > Add a server	Admins, for the whole organization. Lands as Optional

Registry settings

Off removes it everywhere. Optional leaves it for each agent to add. Auto-injected and On by default put it on every agent in its audience. Local stdio entries (a uvx ... command) work on Air-Gapped too. Their actions can be gated for approval like any skill’s.

Whose credential the endpoint receives

Authentication	What the server receives
OAuth	Each person authorizes their own account, so the agent acts with their permissions where the system allows. A token can be shared across a person’s agents.
Signed-in user (SSO)	The asking person’s SSO token as Authorization: Bearer, for endpoints behind an identity-aware gateway. No separate sign-in.

See whose credential a shared agent uses.

Add server with Authentication set to Signed-in user (SSO), Token sent set to Exchange for an audience, and an Audience. Shown with sample data.

How calls behave

• Remote endpoints use HTTP or SSE. Local stdio servers run in the agent’s workspace and are tested at save time.
• When an endpoint asks for input (MCP elicitation), the person answers in the chat, or an app answers over the API.
• Long-running operations (MCP Tasks) run in the background.
• A dropped session reconnects. Connected means a real call worked.

An MCP gateway you already run

Add its endpoints to the registry as above. Both its policy and xpander’s controls apply to xpander’s calls. Its other clients stay outside xpander. It must be reachable from the cluster’s pods, not only the browser.

Verify

kubectl -n xpander port-forward service/xpander-mcp 8081:8081 &
curl http://localhost:8081/health

Runs that arrive through MCP are tagged in Session Manager, for example “MCP - Claude”.

Next steps

Connect a client to Omni

Setup per client.

Let each person sign in

Act as whoever asks.

Add an MCP skill to an agent

Step by step.