> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect an MCP client to Aomi's exact-resource Agent or Pipeline server with OAuth.
Aomi exposes two Streamable HTTP MCP resources. Choose the resource that matches the work:
| Resource | Production URL | Use it for |
| ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Agent MCP | `https://chat.aomi.dev/v1/agent/mcp` | Start or continue Agent turns, read progress, interrupt work, and find account-owned sessions. |
| Pipeline MCP | `https://chat.aomi.dev/v1/pipeline/mcp` | Discover Apps and operation schemas, then execute one operation or a multi-step program directly. |
Use the same paths on another Aomi environment by replacing the origin. Accounts, OAuth grants, sessions, and App inventory are environment-specific.
`/api/mcp` and `/api/mcp/direct` are removed. They are not aliases for the
versioned resources.
## Connect Agent MCP
```bash theme={null}
codex mcp add aomi-agent --url https://chat.aomi.dev/v1/agent/mcp
codex mcp login aomi-agent
```
```bash theme={null}
claude mcp add --transport http aomi-agent \
https://chat.aomi.dev/v1/agent/mcp
```
Run `/mcp` and authenticate **aomi-agent** if the browser flow does not start automatically.
```json theme={null}
{
"mcpServers": {
"aomi-agent": {
"url": "https://chat.aomi.dev/v1/agent/mcp"
}
}
}
```
Configure a Streamable HTTP server at `https://chat.aomi.dev/v1/agent/mcp`. The origin publishes OAuth authorization-server and protected-resource metadata.
Then ask your MCP client to use Aomi, for example:
```text theme={null}
Use Aomi to read my USDC balance on Base, then explain the result.
```
## Agent MCP tools
| Tool | Purpose |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `aomi_chat` | Start a new Agent turn or continue a named session. Auto routing is the default; an Application selector chooses Direct routing. |
| `aomi_check` | Long-poll for new events using the prior opaque cursor. |
| `aomi_interrupt` | Interrupt a specific active turn. |
| `aomi_list_sessions` | List recent sessions owned by the authenticated account. |
### Follow a turn
1. Call `aomi_chat`. Omit `session` to start a conversation, or use an ID returned by `aomi_list_sessions`.
2. Keep the returned `session` and cursor exactly as returned.
3. Call `aomi_check` with the same session and prior cursor while the turn is active or more events remain.
4. Apply events in order. Treat message, tool, task, error, Action, and turn-state events as one event stream.
5. Stop when the turn reaches a terminal state or needs a human Action.
When the response includes a pending Action, send the user to the Aomi portal or an authenticated wallet client. Call `aomi_check` again after approval or rejection. A local signature, submitted transaction, or nonterminal event is not a confirmed result.
## Connect Pipeline MCP
```bash theme={null}
codex mcp add aomi-pipeline \
--url https://chat.aomi.dev/v1/pipeline/mcp
codex mcp login aomi-pipeline
```
Pipeline MCP currently exposes:
| Tool | Purpose |
| ------------------------ | -------------------------------------------------------------------------------- |
| `aomi_get_agent_context` | Resolve the account's deterministic Pipeline thread and initial catalog context. |
| `aomi_list_apps` | List Apps. |
| `aomi_search_apps` | Search Apps by intent or name. |
| `aomi_select_app` | Read one App and its namespace catalog. |
| `aomi_list_namespaces` | List namespaces for an App. |
| `aomi_search_tools` | Search tools, optionally within an App. |
| `aomi_list_tools` | List tools for an App or namespace. |
| `aomi_describe_tool` | Read the exact input schema for one tool. |
| `aomi_call_tool` | Validate and execute one tool call. |
| `aomi_run` | Execute a multi-step program whose intermediate values feed later calls. |
Use a broad-to-narrow workflow:
1. Search or list Apps.
2. Select the App.
3. Search or list its tools.
4. Describe the exact tool to obtain its live schema.
5. Use `aomi_call_tool` for one operation or `aomi_run` for a dependent multi-step flow.
Hosted Apps require their numeric `application_id` and can also require a platform selector. The authenticated resource's live `tools/list` response is the final authority if the inventory changes.
## OAuth and wallet authority
Each MCP URL is an exact OAuth resource:
* Agent MCP requires `mcp:agent` plus the Agent read or write scope needed by the selected tool.
* Pipeline discovery requires `mcp:pipeline` and `pipeline:catalog`.
* Pipeline execution requires `mcp:pipeline` and `pipeline:execute`.
Your MCP client completes OAuth with PKCE and receives credentials for that exact URL. Agent MCP and Pipeline MCP grants are not interchangeable. REST, guest, and MCP credentials are also distinct audiences.
OAuth authorizes the caller. It does not give an MCP client a private key or reusable wallet signature. A pending wallet Action still follows the account's wallet and approval policy.
Authorize only MCP clients you trust. A client with an Agent or Pipeline grant
can use the operations covered by that grant until it expires or you revoke
it.
## Troubleshooting
| Symptom | Check |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Complete the browser login for this exact MCP server. |
| `403 Forbidden` | Re-authenticate this resource; do not reuse an Agent, Pipeline, REST, or guest token from another audience. |
| `404` on `/api/mcp*` | Replace the retired path with `/v1/agent/mcp` or `/v1/pipeline/mcp`. |
| Browser does not open | Use the client's explicit login command or its MCP status UI. |
| Session not found | Confirm the environment and account own that session. |
| Action remains pending | Complete review through the portal or authenticated wallet client, then call `aomi_check` again. |
| Pipeline input rejected | Call `aomi_describe_tool` again and validate against the current schema. |
See [Authentication](/docs/integrate/authentication) and the [authentication reference](/docs/api-reference/authentication) for exact resource and scope behavior.