Agor MCP Server

Anything a user can do in Agor, an agent can do too. The same daemon that serves the UI’s REST and WebSocket APIs also exposes a built-in Model Context Protocol (MCP) server — a structured automation surface that turns every session into a self-aware orchestrator.

This is the foundational layer: assistants, scheduled prompts, cards, artifacts, and the message gateway are all built on top of it.

The other doorway: if you’re driving Agor from outside an agent — TS/JS scripts, custom dashboards, internal services — reach for the official @agor-live/client instead. Same daemon, same types, REST + Socket.IO + a reactive session API.

Key Ideas

• Agents as first-class users: Every MCP tool wraps a FeathersJS service. Sessions, worktrees, boards, zones, users, environments — anything you can click or agor-CLI is available as JSON-RPC.
• Self-aware sessions: Each session is auto-issued a scoped MCP token, so the agent already knows which session, worktree, and board it’s in — and can act on that context.
• No separate server: MCP is part of the daemon. Nothing to install, nothing extra to run.
• Remote access: External agents and dashboards can connect over HTTP to drive Agor (create boards, worktrees, or even invite new users).

MCP is enabled by default and every session already has credentials injected — no setup required for in-Agor agents.

Capabilities At a Glance

Because tools route through FeathersJS services, every action emits the same events the UI listens to—real-time updates appear instantly for everyone watching the board.

Self-Aware Agents Inside Agor

When you launch a session in Agor, the SDK config includes the internal MCP server automatically:

{
  "type": "http",
  "url": "http://localhost:3030/mcp",
  "headers": {
    "Authorization": "Bearer <mcp_token>"
  }
}

The daemon requires the token in the Authorization: Bearer header. Query- string tokens are rejected — don’t put secrets in URLs, where they’d leak into access logs and browser history.

From there agents can:

• Discover their current session and worktree context.
• Spawn subsessions to fan out work (e.g., spin up multiple coders to process a checklist).
• Inspect the board layout to decide where to place new worktrees or sessions.
• Update their own user profile to signal who is speaking.

This self-awareness is what lets agents behave like team members instead of detached copilots.

Automation Examples

• Repository bootstrap: “Clone this GitHub repo, create a worktree for the main branch, and start the dev environment automatically.”
• Zone-based workflows: “Create a ‘Human PR Review’ zone on the board, positioned based on existing zones, with a trigger that prompts for review feedback.”
• Mass subsession fan-out: “Read context/js-to-ts-refactor, split the file list, create a subsession per chunk, and report back when done.”
• Bulk account provisioning: Paste a CSV of emails; the agent calls MCP to create users and invite them automatically.
• Issue triage pipeline: Source GitHub issues by label, triage them, and create worktrees linked to each issue, dropping them onto the active board as cards.
• Environment orchestration: Start/stop worktree environments via MCP before delegating work to collaborators or other agents.

Because MCP calls are just JSON-RPC, complex workflows can be scripted once and reused by any tool that speaks the protocol.

External Agent Access

External agents can use the same MCP endpoint:

1. Obtain an authenticated token (session token for scoped access today; broader API tokens are planned).
2. Connect over HTTP/SSE to http(s)://<daemon-host>:<port>/mcp.
3. Call the same tools internal agents use—no separate API surface required.

This makes Agor a control plane for other AI systems, enabling remote triage bots, automation pipelines, or custom dashboards to work against live boards.

Best Practices

• Keep permission policies tight. MCP calls respect Agor’s permission system—configure approvals so agents only do what the team expects.
• Design idempotent workflows. Make repeated calls safe; agents may retry when handling errors.
• Log agent activity. Sessions capture every MCP action they trigger, making reviews and audits straightforward.
• Reuse concept files. Agents can load context/ docs via MCP, ensuring automations stay aligned with team conventions.

MCP Tokens

MCP session tokens are short-lived JWTs (aud agor:mcp:internal) embedding a jti (per-issuance ID) and an exp. Tokens are re-minted fresh on every GET /sessions/:id and POST /sessions.

There is no revocation mechanics — no per-jti ledger, no session-generation counter. The authorised blast radius of a leak is bounded by exp (default 24h). Validation additionally rejects tokens whose session has been deleted. If/when MCP is opened externally we’d design auth from scratch (OAuth / API keys) rather than extending this.

Access gating

Because an MCP token binds uid = session.created_by and lets the bearer act AS the creator on the MCP channel, it’s only issued to callers who are already allowed to act as that creator:

• GET /sessions/:id — the creator themselves (provided they are still member+), a superadmin, or the executor’s service identity (role: 'service', used when spawning the child process). A plain member+ with view permission on the worktree does not receive a token — handing one out would let them impersonate the creator, sidestepping the session-tier “own sessions only” rule enforced elsewhere.
• POST /sessions — the caller is the creator by construction, so member+ is the only gate here.
• Viewers never receive an mcp_token on either path — they cannot prompt via REST either, so MCP would be useless for them regardless.

Config knobs

execution:
  # Token lifetime — keep short to cap the damage from a leak.
  mcp_token_expiration_ms: 86400000            # 24h (default)

Troubleshooting

Related Reading

• Sessions & Trees — How agents spawn, fork, and ask side questions through MCP
• Assistants — Long-lived agents that drive Agor through MCP
• Scheduler — Cron-style triggers that fire prompts via the same surface
• TypeScript Client — The non-agent doorway: drive Agor from JS/TS apps, scripts, and services
• Architecture: Agor as an MCP Server
• SDK Comparison