Workers and MCP connection
Step 1. Create a worker
In AgentBoard, open Workers → Add worker. Select a client profile: Codex, Claude Code, Gemini CLI, Cursor, OpenCode, Ollama via OpenCode, VS Code Copilot or another MCP client. The profile fills in typical features (code, tests, Git); you can change them. The name is visible on the board, and Slug is a short identifier without spaces for the MCP command. Click Save.
One worker corresponds to one AI personality. Create different workers for different clients or teams. The capability profile describes the specialization, but does not extend the AI's rights to task stages.
Step 2. Copy the configuration
Open the created worker. The MCP diagnostics block shows the configuration fragment and the file where to add it. Click Copy MCP config. If the file already exists, add the suggested server to the existing mcpServers/servers/mcp object without erasing other servers.
The main command looks like this:
agentboard mcp --project C:\Projects\MyFirstProject --worker codex
--project should point to the folder you registered via agentboard init. --worker — Slug of the created worker. The MCP client runs this command itself when it needs tools. In the AgentBoard browser, the web server can run separately.
You can start MCP from any folder with an explicit --project. Without it,
agentboard mcp --worker codex discovers the nearest registered project containing
the current directory, including subdirectories. Outside registered projects it
returns PROJECT_REQUIRED with instructions to specify --project.
The HTTP server's launch folder does not bind MCP workers. MCP reports its project
and launch context in agentboard://current-worker and checks client workspace
roots when the client provides them. If the launch project or workspace conflicts
with the configured project, tools ask for confirmation through MCP elicitation.
Clients without form elicitation receive PROJECT_CONTEXT_MISMATCH before any task
access. Correct the project/worker configuration, or explicitly confirm intentional
cross-project work with --allow-project-mismatch. Workspace changes invalidate
previous confirmations. If a client supplies no roots, only the MCP process's
launch directory is available for automatic detection.
After checking, the diagnostic block contains the absolute path to the running agentboard.exe. It is especially useful when installing from a ZIP. When installing via Scoop, you can use the agentboard command if the client sees the same PATH.
Step 3: Add a server to your client
The worker interface already has a ready-made fragment. Below is an explanation of where it is used:
| Client | Where to insert | How to check on the client side |
|---|---|---|
| Codex | %USERPROFILE%\.codex\config.toml, section [mcp_servers.agentboard_<slug>] |
codex mcp list |
| Claude Code | .mcp.json in project folder |
claude mcp list |
| Gemini CLI | %USERPROFILE%\.gemini\settings.json, object mcpServers |
/mcp list in Gemini CLI |
| Cursor | .cursor\mcp.json project |
list of MCP servers in Cursor settings |
| OpenCode | opencode.json project, object mcp |
list of MCP tools in OpenCode |
| VS Code Copilot | .vscode\mcp.json project, object servers |
command MCP: List Servers |
For Codex and Claude Code, an example with the project C:\Projects\MyFirstProject and the worker codex:
# %USERPROFILE%\.codex\config.toml
[mcp_servers.agentboard_codex]
command = "agentboard"
args = ["mcp", "--project", "C:\\Projects\\MyFirstProject", "--worker", "codex"]
{
"mcpServers": {
"agentboard_codex": {
"type": "stdio",
"command": "agentboard",
"args": ["mcp", "--project", "C:\\Projects\\MyFirstProject", "--worker", "codex"]
}
}
}
In JSON, the Windows backslash is doubled; a ready-made fragment from the interface does this automatically. Generated configurations include the actual --db used by the web server. This keeps HTTP and MCP on the same database even when the client has a different environment.
Ollama provides a local model, but does not replace the MCP client. The Ollama via OpenCode profile generates an MCP configuration for OpenCode; separately configure OpenCode on the Ollama model. Another MCP-compatible client with Ollama is also suitable.
Step 4: Check your connection
- Open the worker card and click Check again. Server check launches the actual stdio executable with this project, worker and database, then verifies the handshake and tool discovery. It does not verify the external AI client's configuration. Enabled is permission to connect, not evidence of a successful connection.
- Start or restart the AI client after adding the configuration file. Have it call
get_my_board. - Client connected will appear in AgentBoard and a new session will appear in the list. Only this confirms the connection of your client. If there are tools, but the client is not connected, check the path to the program, the name of the configuration file and its JSON/TOML syntax.
Start your work session with get_my_board. AI does not receive tasks from Backlog and Complete, even if it knows their ID. AI cannot pretend to be human and does not have a general “move anywhere” command. Working with the file system outside of AgentBoard depends on the capabilities and sandbox of the selected client.
task_id accepts full UUIDs or unique case-insensitive prefixes of at least eight
characters, scoped to the worker's visible assigned tasks. Ambiguous prefixes return
AMBIGUOUS_TASK_ID; hidden tasks do not participate in matching. Source and dependency
IDs in create_feature require full UUIDs. Boards and transitions return compact task
summaries; get_task returns the full context and native screenshot blocks. JSON is
sent once as text, without a duplicate structuredContent payload.
For human or hybrid testing, finish implementation, move the card to testing, add
handoff instructions, and end the session or work on another task. Never wait or poll
for the human. The verification gate remains enforced in the Go service.
record_test_run.status accepts passed, failed, skipped, or manual_required.
create_feature.testing_mode accepts ai, human, or hybrid; priority accepts
critical, high, medium, or low. Artifact kind, test type, and runner are
free-form labels. report_usage.MCPCalls is a cumulative worker-session snapshot
including that call, not a task total; do not sum snapshots. WorkerSessionID and
mcp_calls_scope identify its scope.
Official customer instructions: Codex, Claude Code, Gemini CLI, Cursor, OpenCode, VS Code.