// Use when authoring an AgentWorkforce persona's `mcpServers` field — covers the two spec variants (http/sse vs stdio), `$VAR` secret substitution, the claude/codex/opencode harness support matrix that constrains harness selection, and the `permissions.allow` pairing for `mcp__<server>` tools
| name | persona-mcp-servers |
| description | Use when authoring an AgentWorkforce persona's `mcpServers` field — covers the two spec variants (http/sse vs stdio), `$VAR` secret substitution, the claude/codex/opencode harness support matrix that constrains harness selection, and the `permissions.allow` pairing for `mcp__<server>` tools |
You are advising an author writing the mcpServers field on an AgentWorkforce persona spec. The field declares which MCP servers the persona's harness session should attach to. Map of serverName → spec. The spec shape is uniform across harnesses — persona-kit translates per harness at spawn time.
Remote (http or sse):
"mcpServers": {
"notion": { "type": "http", "url": "https://mcp.notion.com/mcp" }
}
Optional headers map for authentication:
"mcpServers": {
"private-api": {
"type": "http",
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer $MY_API_TOKEN" }
}
}
Local stdio binary:
"mcpServers": {
"posthog": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@posthog/mcp"],
"env": { "POSTHOG_API_KEY": "$POSTHOG_API_KEY" }
}
}
Values inside url, headers, command, args, and env support $VAR / ${VAR} substitution against the caller's process env at spawn time. Use this for secrets — never hardcode API keys in the persona JSON.
If a required field references an unset env var, persona-kit drops that entire mcpServers.<name> block at spawn time with a warning rather than booting with an obviously-broken config.
| Harness | Support | How it works |
|---|---|---|
claude | Fully wired | mcpServers is passed through verbatim via --mcp-config with --strict-mcp-config. The session sees only the persona's declared servers, never the user's local Claude Code config. |
codex | Translated | Each server becomes repeated --config mcp_servers.<name>.{command,args,env,url,http_headers} TOML overrides. stdio and http both work; sse emits a warning and forwards the URL as-is because codex expects streamable-http endpoints. |
opencode | Not wired | The build emits a warning and skips MCP entirely. Do not pick opencode for a persona that needs MCP servers. |
If the persona needs MCP, this constrains harness selection. Default to claude for MCP-heavy personas; choose codex only if you also need codex's reasoning ceiling and can live with the warning-on-sse caveat.
Pair mcpServers with permissions.allow to gate which of a server's tools the agent may invoke:
"permissions": {
"allow": ["mcp__notion", "mcp__posthog__projects-get"]
}
mcp__<server> allows every tool exposed by that server.mcp__<server>__<tool> matches one specific tool.Without an allow entry the harness uses its default permission policy for MCP — under claude that typically means prompts on first use, not auto-approve. For unattended runs, list the allowed tools explicitly.
claude (full support) or codex (translated)? If opencode, MCP will be silently dropped.api_key, token, password) referenced via $VAR substitution, not hardcoded?permissions.allow set to the specific mcp__<server> (or mcp__<server>__<tool>) entries the persona actually uses, especially for unattended runs?stdio servers: is the command (e.g. npx) actually available on the harness machine? If shipping in a container, is the binary pre-installed?Use before auto-merging any PR in an autonomous run, and between consecutive merges that touch overlapping code. Covers the per-PR auto-merge bar (live CI verification, substantive review by area, bot-finding stale-vs-actionable triage) and the cross-PR composition discipline (serialize through green main, rebase + re-CI between merges, dormant-safety audit, force-reset over half-merged commits).
Use at the start of every autonomous, multi-PR, cutover-class delegated run. Authors the binding contract between operator and agent — the gates, the flip mechanism, the rollback triggers, the standing constraints, and the explicit escalate-to-human conditions — and surfaces it to the operator for explicit grant of (a) auto-merge authority, (b) flip-the-switch authority, (c) swarm-blockers authority. No autonomous work begins until the contract is acknowledged.
Use when designing or executing a cutover-class change (migration, ingestion path swap, provider relink, flag enablement). Encodes the dark-launch + single-switch flip pattern, the refusal to flip on amber, and the pre-authorized rollback procedure — the canonical way to make irreversible-feeling infra changes reversible-feeling.
Use when a fix has failed two consecutive times for the same symptom. Encodes the discipline that the third action must be a temporary diagnostic (a /_diag endpoint, an enriched structured log, a runtime-captured snapshot) rather than another fix attempt. Also covers the discipline for removing those diagnostics once the real root cause is in.
Use during an autonomous run to (a) dispatch supporting codex-impl + claude-review agent pairs against hard blockers when the orchestrator cannot make progress alone, and (b) maintain the live RED / GREEN gate scoreboard the orchestrator reads to authorize the flip. Encodes the file-based reporting convention that keeps the channel readable.
Use when a single gate would require deep proof across a large set (44 models × 10 providers; 60+ resources; every region; every plan tier). Splits the acceptance into tier-1 (deep proof on high-volume / high-fidelity slice) and tier-2 (smoke proof on low-volume tail), documents the explicit accepted trade-off, and preserves safety through dormant-default + per-item enable + rollback.