Skip to content
zidane
Server

MCP endpoint

Serve MCP at /mcp on zidane-server, so Claude Code, Cursor or another agent drives its sessions with a token.

A server can serve MCP at /mcp. An MCP client, such as Claude Code, Cursor or another agent, then drives the server's sessions with two tools, sessions and interactions. They are the verbs an orchestrator session holds. MCP is off by default.

Turn it on#

  1. 1

    Start the server with MCP

    Terminal
    zidane server start --mcp

    ZIDANE_SERVER_MCP=1 or "mcp": true in server.json does the same (configuration). zidane server setup --mcp turns it on in a guided setup.

  2. 2

    Create a token for the client

    Terminal
    zidane server token create --name mcp --scope chat

    A chat token drives sessions and answers questions, plans and tool approvals. The guided setup creates this token for you and prints it once.

  3. 3

    Add the server to the client

    Terminal
    claude mcp add --transport http zidane https://zidane.example.com/mcp --header "Authorization: Bearer zds_…"

    For Cursor, in .cursor/mcp.json:

    JSON
    { "mcpServers": { "zidane": { "url": "https://zidane.example.com/mcp", "headers": { "Authorization": "Bearer zds_…" } } } }

The tools#

MCP tools
ToolVerbDoes
sessionsVerbcreateDoesstart a session in a directory with a first prompt (environment: where it runs, e.g. {"kind": "worktree", "branch": "fix/login"} for its own branch and worktree; default local). Returns its sessionId and link. Do NOT wait for it; you will receive a <session-event> in this conversation when it finishes, fails, or needs a decision.
sessionsVerbsendDoesgive a running or idle session a new prompt (queued if it is mid-run).
sessionsVerbsteerDoesinject guidance into a session's CURRENT run at its next turn boundary.
sessionsVerbcancelDoesinterrupt a session's run.
sessionsVerbreadDoesa summary of a session; title, cwd, state (idle/running/blocked), last message (cut at 600 characters), turn count, link. full: true returns the whole last message: use it to get a worker's complete report.
sessionsVerblistDoesother sessions with live status, newest first, capped at 30 by default (raise with limit, max 100); the list may be PARTIAL. worker=true marks the ones you created.
sessionsVerbtranscriptDoesthe last N turns (default 10, max 50) as plain text, each cut at 1200 characters; full: true returns them whole.
sessionsVerbwaitDoesreturn once a session is idle or blocked, or after timeout seconds (default 30, max 50). For callers that do not receive <session-event>s; with events, never wait.
sessionsVerbeventsDoessearch what happened in other sessions (runs that ended, sessions waiting for an answer), newest first: filter by sessionId, status (done/error/cancelled/needs-attention), text, since (an event seq), limit (default 20). Only the sessions you created or sent to report into this conversation; look everything else up here when it matters.
interactionsVerbpendingDoesthe prompts waiting for an answer, of one session (sessionId) or all: requestId, sessionId, kind (question/plan/approval), summary, payload (the questions and choices, the plan, or the tool and its input).
interactionsVerbanswerDoesanswer one by requestId. The first answer wins: if the person or another orchestrator answered first, you are told so.

An MCP client may also create orchestrators: create takes tools and subscribe (orchestrators). It gets no events, so it calls wait (at most 50 seconds, under common client timeouts) and calls again.

Security#

Each tool call runs as a connection that holds the token:

  • The token's scope is checked for each call, and refusals go to the audit log.
  • The sessions the token creates are tagged with it. Revoking the token stops what it started, and its next call gets a 401.
  • The same checks as a WebSocket connection apply: browser origin, proxy and rate limit.
  • No token, or a wrong one, gets a 401. A machine token gets a 403.

The security page covers tokens and scopes.