Skip to main content
The api service is xpander’s REST and MCP entry point for external clients. It fronts the Agent Controller. REST calls carry an API key. The MCP endpoint takes OAuth 2.1 only, on every deployment. Skills served over MCP go the other way: an admin registers the endpoint once, and agents reach it through xpander with the same approvals, credentials and record as any other skill.

​
Inbound: clients reach xpander over MCP

The sign-in is the same on every deployment. A call without a token gets 401 with WWW-Authenticate: Bearer resource_metadata=.../.well-known/oauth-protected-resource. The client registers itself at /oauth/register, sends the person to /oauth/authorize with PKCE, exchanges the code at /oauth/token, and calls /mcp/ with Authorization: Bearer <token>. An x-api-key header gets the same 401. On a self-hosted install the Omni endpoint is the install’s own public MCP URL, global.mcp.publicUrl in the chart (rendered to OMNI_MCP_URL). Until that value is set, /omni-mcp/ answers 404, Settings > Channels lists MCP as Not configured on this install, and the License page’s Capabilities card shows the same MCP endpoint capability as Disabled. There is no separate MCP switch on an agent’s Channels pane; only Omni and API appear there, so the organization’s channel switch is what governs whether the channel is offered. See Channels. The agents endpoint needs one value of its own. /oauth/authorize redirects the browser to ${APP_URL}/oauth_login, read from the api service’s environment, so APP_URL must be the UI origin. With APP_URL on the API host the browser lands on {"detail":"Not Found"}. The chart keys are on Model Context Protocol.

​
Outbound: skills served over MCP

Settings > MCP registry holds two lists. Organization servers are shared with every agent in the organization; admins and each entry’s creator can edit them. Your personal servers are visible only to you, including endpoints registered on their own when you signed in to one from chat. The registry keeps one canonical identity per endpoint, deduplicates by name, shows a health indicator per row and a badge for endpoints that support dynamic client registration. A local stdio entry (a uvx ... command) is accepted on Air-Gapped too. Once registered, an endpoint appears under Add skill on any agent like a catalog skill, and its actions can be marked to wait for approval.
MCP registry page with an Organization servers table holding one local stdio entry and an empty Your personal servers list

Settings > MCP registry: Organization servers with one local stdio entry, and Your personal servers. Shown with sample data.

Add server in the registry, or Custom skill > MCP Connector on an agent, opens the dialog titled Connect an MCP server. Its fields:
  • Name
  • Server type: Remote or Local
  • Server URL
  • Transport: HTTP or SSE
  • Authentication: None, API key, OAuth2 or Headers; a header row’s key defaults to Authorization
  • Add to organization registry: a switch that files the entry under Organization servers
  • Add skill: the button that creates the skill
Step by step on Add a skill. With OAuth, each person can authorize their own account, so the agent acts with that person’s permissions where the system allows; a token can be shared across the agents a person uses. Setup and the flow are on whose credential a shared agent uses. Remote endpoints are reached over HTTP or SSE; local stdio servers run inside the agent’s workspace and are tested at save time. On the API, GET /{org}/mcp_registry/list returns the registry.
Add server dialog in the MCP registry

The MCP registry's Add server dialog: name, server type, URL, transport and authentication. Shown with sample data.

​
An MCP gateway you already run

Register the gateway’s endpoints in the MCP registry. Every skill behind them is then reached through xpander, so the gateway’s own policy and xpander’s approvals, credentials and record both apply to the calls xpander agents make. Calls the gateway receives from other clients stay outside xpander’s controls. The gateway must be reachable from the cluster’s pods, not only from the browser.

​
Verify

Runs that arrive through MCP are tagged with their origin in Task Manager, for example “MCP - Claude”.