> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Omni MCP Server
> Chat with your Omni agent and operate the platform from Claude, ChatGPT, and other MCP clients
Omni is your personal Xpander router agent: it can answer directly, task your other agents, build and edit agents, manage schedules, and search your organization's knowledge. The Omni MCP server puts all of that behind a single endpoint you connect to Claude, ChatGPT, Cursor, or any MCP-compatible client, so you work with Omni without leaving the tool you're already in.
```
https://omni.xpander.ai/mcp
```
Once connected, you can:
* Chat with Omni straight from your MCP client, and keep the conversation going across turns
* Kick off long-running work asynchronously and poll for the result
* Ask Omni to task your other agents, build or edit agents, and search your organization's knowledge - all through the conversation
* Authenticate once with OAuth 2.1 - you sign in with your Xpander credentials, and every call runs with your permissions
This is a different endpoint from the [per-agent MCP server](/guides/deploy/mcp) (`mcp.xpander.ai/ag_...`), which exposes one specific agent. The Omni MCP server is scoped to **you**: your OAuth sign-in resolves your personal Omni agent and applies your access.
## Tools
| Tool | What it does |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `ask_omni` | Send Omni a message and wait for its answer. Returns Omni's Markdown reply plus a `conversation_id`. |
| `ask_omni_async` | Send Omni a message without waiting. Returns the `conversation_id` immediately; poll with `get_omni_task`. |
| `get_omni_task` | Check the status and result of a conversation started with `ask_omni` / `ask_omni_async`. |
These three tools are deliberately the whole surface: everything else - discovering agents, building them, managing tasks, searching knowledge - happens by asking Omni for it in the conversation. Omni acts with your permissions, so which agents and data a request can touch is always bounded by your own access. If you want a raw tool surface for one specific agent instead, use the [per-agent MCP server](/guides/deploy/mcp).
### Multi-turn conversations
Every answer includes a `conversation_id`. Pass it back into `ask_omni` (or `ask_omni_async`) to continue the same conversation - Omni keeps the full thread, exactly like a chat.
```text theme={"dark"}
You: ask_omni("What did the support agent handle this week?")
Omni: Conversation ID: task_abc123
This week the support agent closed 42 tickets...
You: ask_omni("Draft a summary email to the team", conversation_id="task_abc123")
Omni: Conversation ID: task_abc123
Here's a draft: ...
```
### Long-running work
Omni runs can take from seconds to minutes (tool calls, multi-step reasoning, tasking other agents). For work that might exceed your client's tool-call timeout, start it with `ask_omni_async` and poll `get_omni_task` with the returned `conversation_id` until it's done.
## Authentication
The Omni MCP server authenticates with **OAuth 2.1 only** - there are no API keys to copy into config files. Clients that support remote MCP OAuth (ChatGPT custom connectors, Claude via `mcp-remote`, Cursor, and most modern MCP clients) discover the flow automatically from the server URL. You sign in once in the browser with your Xpander credentials, the client stores the token, and every call runs as you.
Because the sign-in is personal, the connection is too: Omni resolves to **your** Omni agent, sees your conversations, and acts with your access - nothing to configure.
## Connect from a client
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) and add the Omni server. With OAuth, `mcp-remote` runs the sign-in flow the first time you start Claude:
```json theme={"dark"}
{
"mcpServers": {
"xpander-omni": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://omni.xpander.ai/mcp"
]
}
}
}
```
Restart Claude Desktop after saving; `mcp-remote` opens the browser sign-in the first time. Then ask: *"Ask Omni what my agents did today."*
In ChatGPT, add a custom connector pointing at `https://omni.xpander.ai/mcp`. ChatGPT runs the OAuth flow; sign in with your Xpander credentials to authorize it. Once connected, the `ask_omni` tools appear in the connector's tool list.
Add the server to your client's MCP config with the URL `https://omni.xpander.ai/mcp`. The client discovers the OAuth flow from the URL and opens the sign-in on first use.
## How Omni responds over MCP
Runs that arrive through the MCP server are marked as MCP-sourced, and Omni adapts to the channel: because MCP clients render plain Markdown (no interactive Xpander cards), Omni answers in clean, self-contained Markdown and never raises a card that would stall the run. If a task needs something it can't get non-interactively - a missing secret, or a connector that needs authorization - Omni does as much as it can and tells you in its reply what's missing and how to resolve it in the Xpander app.
In the Xpander app, these conversations show up in your task list tagged with their origin - for example "MCP - ChatGPT" or "MCP - Claude" - so you can always tell which client a run came from.
If Omni needs you to authorize a connector mid-run, `ask_omni` returns the authorization link right away along with the `conversation_id`. Complete the authorization, then fetch the result with `get_omni_task` - the run resumes on its own.
## Troubleshooting
The server is OAuth-only - an `x-api-key` header (or any static key) is not accepted. Remove any key-based config, re-add the connector, and complete the browser sign-in with your Xpander credentials.
* Make sure the connector URL is exactly `https://omni.xpander.ai/mcp`.
* Complete the sign-in in the browser window the client opens; some clients cache a stale token - remove and re-add the connector to restart the flow.
Open the link from Omni's reply, complete the authorization in the Xpander app, then call `get_omni_task` with the same `conversation_id` to get the finished result.
## Next steps
Expose a single Custom Agent as its own MCP server
Learn what Omni can do across the platform