You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Expose CCS as an MCP server (drive chats and tasks from an external Claude) #150
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.
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:
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.
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.
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.
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:
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).
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.
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.
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.
mcp-ccs.js — a self-contained stdio MCP server (zero dependencies, no sibling files to copy), speaking httporhttps. 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.
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.
Activity
Lexus2016 commentedon Nov 20, 2026
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.jsover/api/internal/task-manageris an internal door, not a contract. Here is what a supported entry point actually needs, from inside the code: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.GET /api/projects,GET/POST/PUT/DELETE /api/tasks,GET /api/tasks/running-sessionsandPOST /api/tasks/dispatchalready coverlist_projects,create_task,list_tasks,get_task_resultand a cancel path. What they lack is a documented contract and an explicitprojectargument instead of inheriting a workdir from the caller's task — that part is real but contained.GET /api/sessions/:id/messagesonly reads history.create_chatcan reusePOST /api/sessionswith project defaults, butsend_message/get_messages/stop_turnneed 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 othermcp-*.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
projectargument (no implicit workdir) will be part of that design.malys commentedon Nov 21, 2026
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
claudeclient:mcp-ccs.jswill run in another container and reach CCS at something likehttp://claude-code-studio:3000, not127.0.0.1. Please keep the URL configurable (andhttps://supported, the current helper only useshttp).mcp-task-manager.jsneedstask-text-limit.jsnext to it. A single self-contained file (or annpx-able entry) makes it easy to drop into another image and to keep in sync with CCS updates.projectoncreate_task, as you said — an outside client has no parent task to inherit a workdir from. Astatus: "backlog"default (or at least the option) would also be nice for an external caller, since atodotask immediately starts an unattended run.todotasks 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.
Lexus2016 commentedon Nov 21, 2026
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), speakinghttporhttps. Two variables:CCS_URL(any reachable address, path prefix allowed —http://claude-code-studio:3000orhttps://host/ccs) andCCS_TOKEN. Tools:list_projects,list_tasks,get_task,get_task_result,create_task,cancel_task.node scripts/api-token.js create --name mcphub --scope read(alsolist/revoke <id>, and the same overPOST /api/api-tokensfrom 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.readlists and reads;fullalso creates and cancels. A token that can createtodotasks is code execution in the container, so monitoring can stay onread— the wrapper returns a "this token is read-only" error if it tries to write.projectoncreate_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.statusdefaults tobacklog, as you asked: the card lands on the board and nothing runs until you passstatus: "todo"(optionally withscheduled_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.jsdrives the REST surface and then runsmcp-ccs.jsas 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.jspins the store: plaintext never on disk, a malformed file fails closed, revocation is immediate. Both are innpm test. Docs:docs/EXTERNAL-API.mdin the branch — rendered here.When you try it against MCPHub: the external API refuses any request carrying an
Originheader (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_turnneed the server-side contract first, and that is the next design step rather than a wrapper job.external api: a token-authenticated MCP surface for outside agents (#150
Lexus2016 commentedon Nov 21, 2026
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:
Then give the MCPHub server
CCS_URL=http://claude-code-studio:3000andCCS_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 beingtask-backlog.test.js, which fails identically on unmodifiedmainin this container (its second server onlocalhost:4553does 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.