Files
kandev/docs/specs/integrations/external-mcp.md
T
2026-08-19 10:32:40 +01:00

83 lines
5.2 KiB
Markdown

---
status: draft
created: 2026-04-28
owner: tbd
---
# External MCP Endpoint
## Why
Users want to operate on Kandev workspaces, workflows, agents, and tasks from coding agents (Claude Code, Cursor, Codex, …) running outside Kandev. Today the Kandev MCP is embedded inside each `agentctl` instance, scoped to a single session, and reachable only on a container-internal `localhost` port — there is no way to add Kandev as an MCP server in an external agent's global config.
## What
- The Kandev backend exposes an MCP server on its existing HTTP port (default `38429`). The MCP routes are reachable from any network that can reach the Kandev backend.
- Users register Kandev as an MCP server in their external coding agent using one of:
- Streamable HTTP: `http://localhost:38429/mcp`
- SSE: `http://localhost:38429/mcp/sse`
- The external endpoint exposes the **config-mode tool surface** plus `create_task_kandev` (no plan tools, no `ask_user_question_kandev`).
- The endpoint requires a personal access token when Kandev authentication is enabled. It remains open when authentication is disabled.
- The Settings UI shows the URL and ready-to-paste config snippets for popular agents.
- The existing per-`agentctl` MCP behavior is unchanged — the same tool definitions back both endpoints.
- The configuration and external tool surfaces expose `export_workflow_kandev`.
- `export_workflow_kandev` requires one `workflow_id` and returns a JSON `WorkflowExport` document as MCP text content.
- The document uses `version: 1` and `type: kandev_workflow`. It contains exactly one portable workflow and all of its steps.
- The document omits instance IDs and timestamps. It keeps portable profile data and position-based step references from the existing export service.
- A caller can pass the returned text unchanged as `document` to `import_workflow_kandev` when the document is within the import limit.
- Workflow export is read-only. It does not change the workflow, its steps, or its workspace.
## API surface
### `export_workflow_kandev`
Available surfaces: configuration MCP and external MCP.
Input:
```json
{"workflow_id":"workflow-uuid"}
```
Success result: MCP text content that contains an indented JSON `WorkflowExport` document.
The output uses the existing portable workflow contract. The tool does not define a second export format.
## Permissions
The tool uses the caller identity that Kandev attaches to the MCP request. The existing workflow service authorizes the workflow through its workspace.
The tool does not return a workflow from another user's workspace. Authentication-disabled installations keep their current unscoped, single-user behavior.
## Failure modes
- A missing or empty `workflow_id` returns a tool error before backend export work starts.
- An unknown or inaccessible workflow returns a tool error and no partial document.
- A workflow or step read error returns a tool error and no partial document.
- `import_workflow_kandev` keeps its existing 1 MiB document limit. This feature does not add an export limit or change that import limit.
## Scenarios
- **GIVEN** a running Kandev backend, **WHEN** a user adds `http://localhost:38429/mcp` to their Claude Code MCP config and asks "list my Kandev workspaces", **THEN** Claude Code calls `list_workspaces_kandev` and returns the workspaces that appear in the Kandev UI.
- **GIVEN** the user is in a Cursor session outside Kandev, **WHEN** they ask Cursor to "create a task to fix the login bug in workspace X", **THEN** the task appears in the Kandev kanban board.
- **GIVEN** the user opens Kandev Settings → External MCP, **WHEN** they click "Copy Claude Code config", **THEN** they receive a JSON snippet they can paste into `~/.claude.json`.
- **GIVEN** an external agent calls a session-scoped tool that does not exist on this endpoint, **THEN** the call returns a tool-not-found error and the rest of the session is unaffected.
- **GIVEN** a caller can read a workflow, **WHEN** it calls `export_workflow_kandev` with that workflow ID, **THEN** it receives one valid portable workflow document with all workflow steps.
- **GIVEN** an exported document is within 1 MiB, **WHEN** the caller passes the result unchanged to `import_workflow_kandev`, **THEN** import accepts the document and applies existing deduplication rules.
- **GIVEN** a caller cannot read a workflow, **WHEN** it calls `export_workflow_kandev` with that workflow ID, **THEN** the call returns an error without workflow data.
- **GIVEN** a task or Office MCP surface, **WHEN** the client lists tools, **THEN** `export_workflow_kandev` is absent.
## Out of scope
- New authentication methods or changes to personal access tokens.
- Session-scoped tools (`create_task_plan_kandev`, `ask_user_question_kandev`, plan get/update/delete).
- Per-workspace scoping of the endpoint.
- Exposing `agentctl`'s per-session MCP externally — architectural mismatch (per-session, ephemeral, no auth boundary).
- A workspace-level `export_workflows_kandev` batch tool.
- Changes to the portable workflow format or the 1 MiB import limit.
- Changes to the existing HTTP export endpoints or workflow export UI.
## Implementation plan
See [Workflow MCP export](../../plans/workflow-mcp-export/plan.md).