MCP Servers

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

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:

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.
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.
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.
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.):

{
  "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

Agent Detail → MCP Servers tab
Click Add Server → enter config
Toggle Enabled to activate for this agent
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

# 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