---
description: "MCP (Model Context Protocol) servers connect agents to external tools and data sources."
---

# MCP Servers

MCP (Model Context Protocol) servers connect agents to external tools and data sources. Configure them once, assign to agents, and they're available at runtime.


## MCP Server Configuration

### Per-Agent

Each agent has an **MCP Servers** tab in Agent Detail:

- **Add Server** — Name, URL, optional auth headers
- **Test Connection** — Verify before saving
- **Enable/Disable** — Toggle per-server per-agent
- **Status** — Shows last connection status
- **Connect (OAuth)** — For servers that require you to sign in (see below)

### Connecting with OAuth

Some MCP servers need you to sign in instead of using a fixed header. For those:

1. In the server's row, press **Connect (OAuth)**. The dialog **Connect MCP server via OAuth** explains that you will be sent to the server's sign-in page in this browser tab and returned here afterwards.
2. If the provider needs a pre-registered redirect address, copy the exact redirect URI shown in the dialog into the provider's OAuth app settings.
3. Only if the server cannot register a client automatically or be discovered, fill in the manual fields (client ID, an optional client secret and the endpoints). The dialog tells you when a client ID is required.
4. Press **Continue**, sign in at the provider, and you return to the agent.

The row then shows **OAuth · connected**, **OAuth · pending** (sign-in started but not finished) or **OAuth · error**. **Re-auth** runs the sign-in again.

Every user connects **as themselves**. The OAuth app (client) is set up once per server and reused, so when a colleague has already connected the server you only press **Connect (OAuth)** and sign in — no client ID is needed. Each user's token is stored encrypted, belongs to that user, is never displayed, and is added to the Runs **that user starts**. **Disconnect** removes only your own connection; other users stay connected.

Scheduled and recurring tasks have no user behind them. They use the one connection marked **Use for unattended Runs** (tick it in the connect dialog; it moves to you if someone else had it). If a Run's starter has no connection and none is marked for unattended Runs, the Run still starts, without the token, and says so in its log.

To switch the server to a different OAuth app, open **Use a different OAuth app** in the dialog. That replaces the app for everyone, and the other users' connections then show **OAuth · error** until they reconnect.

### Global (System Admin)

**Global Settings** → **AO MCP** tab shows the built-in AO MCP server:

- **Overview** — What it exposes
- **Security** — Guards and access control
- **Available Tools** — Full tool catalog (read/write classified)
- **Connect CLI** — Snippet to register as remote MCP in opencode

## Available MCP Servers

### 1. Custom MCP Servers

Add any MCP-compatible server (filesystem, database, API, etc.):

```json
{
  "name": "My Database",
  "url": "http://db-mcp:3000",
  "headers": { "Authorization": "Bearer <token>" }
}
```

### 2. AO MCP Server (Built-in)

Exposes Agent Orchestrator's REST API as MCP tools for agents and CLI.

**Tools exposed:**
| Tool | Type | Description |
|------|------|-------------|
| `ao_list_agents` | read | List agents in workspace |
| `ao_get_agent` | read | Get agent details |
| `ao_create_agent` | write | Create agent (daemon-only, admin grant) |
| `ao_update_agent` | write | Update agent (daemon-only, admin grant) |
| `ao_list_skills` | read | List skills |
| `ao_get_skill` | read | Get skill details |
| `ao_create_skill` | write | Create skill draft |
| `ao_update_skill` | write | Update skill draft |
| `ao_assign_skill` | write | Assign skill to run's agent |
| `ao_list_runs` | read | List runs |
| `ao_get_run` | read | Get run details |
| `ao_list_tasks` | read | List tasks |
| `ao_create_task` | write | Create task |
| `ao_list_runtimes` | read | List runtimes |
| `ao_search_knowledge` | read | Search knowledge base |

**Access control:**
- Per-agent **Include AO Tools** grant (Context tab)
- Daemon-mode only (not in standalone CLI)
- System Admin sees full catalog in Global Settings

### 3. Agent Memory MCP (Built-in)

Gives agents RAG access to knowledge folders during runs.

**Tools:**
| Tool | Description |
|------|-------------|
| `memory_search` | Semantic search across readable folders |
| `memory_remember` | Save content to personal folder |
| `memory_list_folders` | List accessible folders |
| `memory_create_folder` | Create new personal folder |

**Access:**
- Enabled per-agent via **Include Knowledge** (Context tab)
- Read = personal + workspace-global + project folders
- Write = personal folders only
- Started per-run, stopped when run finishes

## Assigning MCP Servers to Agents

1. **Agent Detail** → **MCP Servers** tab
2. Click **Add Server** → enter config
3. Toggle **Enabled** to activate for this agent
4. At runtime, enabled servers injected into agent's context

## Security

All MCP connections go through guards:

| Guard | Purpose |
|-------|---------|
| **Non-loopback Host** | Blocks external hosts in daemon mode |
| **JSON-only** | Rejects non-application/json POST |
| **Bearer Auth** | Per-run random secret (daemon) or `AO_MCP_LOCAL_SECRET` (standalone) |
| **Per-agent grants** | `include_ao_tools`, `include_knowledge`, `include_agent_admin` |

## Using in Standalone CLI

Register AO as a remote MCP server in opencode:

```bash
# Get snippet from Global Settings → AO MCP → Connect CLI
# Adds to opencode config:
{
  "mcpServers": {
    "agent-orchestrator": {
      "url": "https://your-ao.com/api/daemon/runs/<runId>/mcp",
      "headers": { "Authorization": "Bearer <per-run-secret>" }
    }
  }
}
```

## Recent Updates

- **AO MCP Server** — Expose AO REST API as opencode tools for agents and CLI
- **Agent Memory MCP** — RAG search, save to personal folders during runs
- **Per-agent Grants** — Granular control: AO Tools, Knowledge, Agent Admin
- **Tool Catalog** — Read/write classification in Global Settings