Skip to content

Expose CCS as an MCP server (drive chats and tasks from an external Claude) #150

Closed

Description

@malys

Problem

I want to drive Claude Code Studio from an external Claude Code session (or any MCP client): create work, follow it, read results, without opening the web UI. Today CCS is an MCP client only. Its internal MCP servers (_ccs_task_manager, _ccs_bots, …) are injected into the claude runs CCS starts itself, and nothing is exposed to an outside agent.

This is different from #149, which is about managing the MCP servers CCS hands to its agents.

What already works (tested on 8.1.0, in Docker)

mcp-task-manager.js can already be run as a stdio MCP server by an external client, if it gets the server URL and the Bearer secret:

"ccs": {
  "command": "docker",
  "args": ["exec", "-i", "-u", "bun",
           "-e", "TASK_MANAGER_SERVER_URL=http://127.0.0.1:3000",
           "-e", "TASK_MANAGER_SECRET",
           "claude-code-studio", "node", "/app/mcp-task-manager.js"],
  "env": { "TASK_MANAGER_SECRET": "<same value as CCS_TASK_MANAGER_SECRET in the container>" }
}

initialize, tools/list and list_tasks answer correctly from outside a task (no TASK_MANAGER_TASK_ID).

Limits of that workaround:

  • /api/internal/task-manager is an internal door, not a documented contract; it may change in any release.
  • Without CCS_TASK_MANAGER_SECRET, the secret is random per process, so the client breaks on every CCS restart.
  • It only covers the Kanban board. There is no tool for chats: create a chat in a project, send a message, read the reply, stop a turn.
  • Tasks created with no parent task: I have not checked which project/workdir they land in.

Proposed change

A supported, documented "CCS as MCP server" entry point, for example mcp-ccs.js (stdio, same zero-dependency style as the other mcp-*.js), authenticated with a dedicated token instead of the internal task-manager secret. Minimal tool set:

  • list_projects
  • create_task / list_tasks / get_task_result / cancel_task (reuse the existing handlers, with an explicit project argument)
  • create_chat(project, text, model?, engine?) → session id
  • send_message(session_id, text) and get_messages(session_id, since?)
  • stop_turn(session_id)

Chats first would be enough for my use case; the task tools already exist.

Constraints

  • Opt-in, off by default; no change for existing users.
  • Token stored like other secrets, never logged.
  • Same rules as the task-manager endpoint for tunnels, proxies and browser Origin.

Activity

  1. Lexus2016 commented on Nov 20, 2026

    @Lexus2016
    Owner

    Thanks — this is well researched, and the distinction from #149 is clear: #149 is about the servers CCS hands to its own agents, this is about CCS itself being a server for an outside agent.

    You are right that mcp-task-manager.js over /api/internal/task-manager is an internal door, not a contract. Here is what a supported entry point actually needs, from inside the code:

    1. Auth. The REST API accepts login session tokens today (x-auth-token / Authorization: Bearer, 64-hex, TTL-bound, revoked on password change). There is no long-lived API token. A dedicated, revocable token (hashed at rest, shown once, off by default) is a small change, and it is a prerequisite for any external client.
    2. Projects and tasks are reusable as-is. GET /api/projects, GET/POST/PUT/DELETE /api/tasks, GET /api/tasks/running-sessions and POST /api/tasks/dispatch already cover list_projects, create_task, list_tasks, get_task_result and a cancel path. What they lack is a documented contract and an explicit project argument instead of inheriting a workdir from the caller's task — that part is real but contained.
    3. Chats are the blocker. Sending a message is not a REST call: the web UI drives turns over the app WebSocket, and GET /api/sessions/:id/messages only reads history. create_chat can reuse POST /api/sessions with project defaults, but send_message / get_messages / stop_turn need either a documented WebSocket sub-protocol or a small REST + SSE surface on the server first. The MCP file itself is the easy part.

    So my plan is two stages: stage 1 — mcp-ccs.js (stdio, zero-dependency, same style as the other mcp-*.js) exposing projects and tasks over a dedicated token, opt-in and off by default; stage 2 — chats, after the send/stop contract exists server-side.

    One question so I build the right thing first: is stage 1 (projects + tasks from an external MCP client) useful to you on its own, or is creating a chat and sending a message the part you need first? If it is chats, I will design the REST/SSE surface before writing the MCP wrapper, and an explicit project argument (no implicit workdir) will be part of that design.

  2. malys commented on Nov 21, 2026

    @malys
    Author

    Thanks for the breakdown — stage 1 first, please. Projects + tasks from an external MCP client is useful on its own; chats can wait for the send/stop contract.

    Context that may shape stage 1: the target client is MCPHub, which runs stdio servers in its own container and re-exposes them over HTTP. So a few points matter beyond a local claude client:

    1. Remote base URL. mcp-ccs.js will run in another container and reach CCS at something like http://claude-code-studio:3000, not 127.0.0.1. Please keep the URL configurable (and https:// supported, the current helper only uses http).
    2. Copyable / standalone file. Today mcp-task-manager.js needs task-text-limit.js next to it. A single self-contained file (or an npx-able entry) makes it easy to drop into another image and to keep in sync with CCS updates.
    3. Explicit project on create_task, as you said — an outside client has no parent task to inherit a workdir from. A status: "backlog" default (or at least the option) would also be nice for an external caller, since a todo task immediately starts an unattended run.
    4. Token scope. A token that can create todo tasks is effectively code execution in the container. A read-only scope (list projects/tasks, get results) next to the full one would let me wire monitoring without that risk — not required for a first version.

    Happy to test stage 1 against MCPHub in Docker as soon as there is a branch.

  3. Lexus2016 commented on Nov 21, 2026

    @Lexus2016
    Owner

    Stage 1 is built → #151.

    What's in it

    • mcp-ccs.js — a self-contained stdio MCP server (zero dependencies, no sibling files to copy), speaking http or https. Two variables: CCS_URL (any reachable address, path prefix allowed — http://claude-code-studio:3000 or https://host/ccs) and CCS_TOKEN. Tools: list_projects, list_tasks, get_task, get_task_result, create_task, cancel_task.
    • Dedicated tokens, not the internal task-manager secret: node scripts/api-token.js create --name mcphub --scope read (also list / revoke <id>, and the same over POST /api/api-tokens from a logged-in session). The plaintext is shown once; only a SHA-256 is stored (data/api-tokens.json, mode 0600). Revoking one does not log the owner out, and it takes effect on the next request.
    • Scopes, as you suggested: read lists and reads; full also creates and cancels. A token that can create todo tasks is code execution in the container, so monitoring can stay on read — the wrapper returns a "this token is read-only" error if it tries to write.
    • Explicit project on create_task, required — nothing is inherited from a task that does not exist here. It takes an id or an exact name; an ambiguous name is refused with the candidate ids instead of picking one.
    • status defaults to backlog, as you asked: the card lands on the board and nothing runs until you pass status: "todo" (optionally with scheduled_at). A task created this way gets its own git worktree, exactly like a card created in the UI.
    • /api/external/v1/* is the whole contract (me, projects, tasks, tasks/:id, tasks/:id/result, tasks/:id/cancel). It sits in front of the session auth wall, so an external token cannot reach chats, files, settings or terminals.

    Tests and docs

    test/external-api.test.js drives the REST surface and then runs mcp-ccs.js as a real stdio MCP client (initialize → tools/list → tools/call) against a live server: read token refused on create, missing project refused, unknown project 404, backlog stays backlog, a revoke kills the token on the next call. test/api-token.test.js pins the store: plaintext never on disk, a malformed file fails closed, revocation is immediate. Both are in npm test. Docs: docs/EXTERNAL-API.md in the branch — rendered here.

    When you try it against MCPHub: the external API refuses any request carrying an Origin header (browsers attach one, stdio clients never do), and the wrapper prints the server's error text verbatim, so a 401 says "check CCS_TOKEN" instead of just failing.

    Chats remain stage 2 as agreed — send_message / stop_turn need the server-side contract first, and that is the next design step rather than a wrapper job.

  4. Lexus2016 commented on Nov 21, 2026

    @Lexus2016
    Owner

    Merged as b8a9e65 — stage 1 is on main, so it is testable against a normal checkout or a rebuilt image (no branch needed).

    Quick start for your MCPHub run:

    docker exec -it claude-code-studio node scripts/api-token.js create --name mcphub --scope read

    Then give the MCPHub server CCS_URL=http://claude-code-studio:3000 and CCS_TOKEN=<the printed token>. CI was green on both matrix cells (Node 20 and 24) before the merge; the local full-suite run is 100 of 101 files, the one exception being task-backlog.test.js, which fails identically on unmodified main in this container (its second server on localhost:4553 does not come up here).

    Keeping this open for stage 2 (chats). If anything in the REST shapes is awkward for MCPHub, say so before the chat contract is designed — a shape change is cheap now and expensive once both exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions