molecule-ai/molecule-core
35
0
Fork 2
Code Issues 16 Pull Requests 2 Actions 49 Packages Projects Releases Wiki Activity
fix/s8-bind-loopback-dev
molecule-core/docs/guides/mcp-server-setup.md
Hongming Wang eec4ea2e7d chore: delete TeamHandler.Collapse + docs cleanup (closes #2864) 
Multi-model retrospective review of #2856 (Phase 1 Expand removal)
flagged that TeamHandler.Collapse is unreachable from the canvas UI:
the "Collapse Team" button calls PATCH /workspaces/:id { collapsed }
(visual flag toggle on canvas_layouts), NOT POST /workspaces/:id/collapse.
The destructive POST route — which stops EC2s, marks children removed,
and deletes layouts — has zero UI callers (verified via grep across
canvas/, scripts/, and the MCP tool registry; only docs referenced it).

Two semantically different operations had been sharing the word
"Collapse":

- Visual collapse (canvas) → PATCH { collapsed: true }. Hides
  children visually. Reversible. UI-only.
- Destructive collapse (POST /collapse) → Stops + marks removed.
  Irreversible. No caller.

Deleting the destructive one + its supporting machinery:

- workspace-server/internal/handlers/team.go (entirely)
- workspace-server/internal/handlers/team_test.go (entirely)
- POST /collapse route + teamh init in router.go
- findTemplateDirByName helper (zero non-test callers after Expand
  was deleted in #2856; package-private so no out-of-package consumers)
- NewTeamHandler constructor (no callers after route removed)

Plus stale doc references (the most dangerous was the MCP wrapper
mapping in mcp-server-setup.md — anyone generating MCP tool wrappers
from that table was wiring a 404):

- docs/agent-runtime/team-expansion.md (deleted entirely — whole
  guide taught the deleted flow)
- docs/api-reference.md (dropped two team.go rows)
- docs/api-protocol/platform-api.md (dropped /expand + /collapse
  rows)
- docs/architecture/molecule-technical-doc.md (dropped /expand +
  /collapse rows)
- docs/guides/mcp-server-setup.md (dropped expand_team +
  collapse_team MCP wrapper mappings)
- docs/glossary.md (dropped "(org template expand_team)"
  parenthetical)
- docs/frontend/canvas.md (dropped broken link to deleted
  team-expansion.md)

Kept: docs/architecture/backends.md mention of "TeamHandler.Expand
(#2367) bypassed routing on Start" — correct historical context for
the AST gate's existence, no live route reference.

Visual-collapse path unaffected:
  canvas/src/components/ContextMenu.tsx:227 → api.patch — unchanged
  canvas/src/components/WorkspaceNode.tsx:128 → api.patch — unchanged

go vet ./... clean. go test ./internal/handlers/ -count 1 — all green
(4.3s, no regression).

Net: -388/+10 = ~378 lines removed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 11:59:43 -07:00

244 lines
10 KiB
Markdown
Raw Permalink Blame History

# MCP Server Setup Guide
The Molecule AI MCP server lets any MCP-compatible AI agent manage workspaces, agents, secrets, memory, schedules, channels, and more through the platform API. It works with Claude Code, Cursor, and any other tool that speaks the MCP protocol.
## Quick Start
### 1. Install
The MCP server is published as `@molecule-ai/mcp-server` on npm.
```bash
npx @molecule-ai/mcp-server
```
### 2. Configure in `.mcp.json`
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"molecule": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@molecule-ai/mcp-server"],
"env": {
"MOLECULE_URL": "http://localhost:8080"
}
}
}
}
```
For production/SaaS deployments, set `MOLECULE_URL` to your tenant URL:
```json
"MOLECULE_URL": "https://your-org.moleculesai.app"
```
### 3. Verify
Once configured, your MCP client should show 87 Molecule AI tools. Test with:
```
list_workspaces
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MOLECULE_URL` | `http://localhost:8080` | Platform API URL |
## Tool Reference
### Workspace Management
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_workspaces` | `/workspaces` | GET | List all workspaces |
| `get_workspace` | `/workspaces/:id` | GET | Get workspace details |
| `create_workspace` | `/workspaces` | POST | Create a new workspace |
| `update_workspace` | `/workspaces/:id` | PATCH | Update workspace fields |
| `delete_workspace` | `/workspaces/:id` | DELETE | Delete a workspace |
| `restart_workspace` | `/workspaces/:id/restart` | POST | Restart workspace container |
| `pause_workspace` | `/workspaces/:id/pause` | POST | Pause workspace |
| `resume_workspace` | `/workspaces/:id/resume` | POST | Resume paused workspace |
| `discover_workspace` | `/registry/discover/:id` | GET | Get workspace URL + agent card |
### Agent Management
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `assign_agent` | `/workspaces/:id/agent` | POST | Assign agent to workspace |
| `remove_agent` | `/workspaces/:id/agent` | DELETE | Remove agent |
| `replace_agent` | `/workspaces/:id/agent` | PATCH | Replace agent config |
| `move_agent` | `/workspaces/:id/agent/move` | POST | Move agent to different workspace |
### Communication
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `chat_with_agent` | `/workspaces/:id/a2a` | POST | Send A2A message to agent |
| `async_delegate` | `/workspaces/:id/delegate` | POST | Fire-and-forget delegation |
| `check_delegations` | `/workspaces/:id/delegations` | GET | Check delegation status |
| `send_channel_message` | `/workspaces/:id/channels/:channelId/send` | POST | Send to social channel |
| `notify_user` | `/workspaces/:id/notify` | POST | Push notification to canvas |
| `list_peers` | `/registry/:id/peers` | GET | Find sibling/parent workspaces |
| `check_access` | `/registry/check-access` | POST | Check if two workspaces can communicate |
### Configuration
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `get_config` | `/workspaces/:id/config` | GET | Get workspace config.yaml |
| `update_config` | `/workspaces/:id/config` | PATCH | Update config fields |
| `get_model` | `/workspaces/:id/model` | GET | Get configured LLM model |
### Secrets
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_secrets` | `/workspaces/:id/secrets` | GET | List workspace secret keys |
| `set_secret` | `/workspaces/:id/secrets` | POST | Set a workspace secret |
| `delete_secret` | `/workspaces/:id/secrets/:key` | DELETE | Delete a secret |
| `list_global_secrets` | `/settings/secrets` | GET | List global secrets |
| `set_global_secret` | `/settings/secrets` | PUT | Set a global secret |
| `delete_global_secret` | `/settings/secrets/:key` | DELETE | Delete global secret |
### Memory
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `memory_list` | `/workspaces/:id/memory` | GET | List memory keys |
| `memory_get` | `/workspaces/:id/memory/:key` | GET | Get memory value |
| `memory_set` | `/workspaces/:id/memory` | POST | Set memory key-value |
| `memory_delete_kv` | `/workspaces/:id/memory/:key` | DELETE | Delete memory key |
| `search_memory` | `/workspaces/:id/memories` | GET | Full-text search memories |
| `commit_memory` | `/workspaces/:id/memories` | POST | Commit HMA memory |
| `delete_memory` | `/workspaces/:id/memories/:id` | DELETE | Delete HMA memory |
### Files
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_files` | `/workspaces/:id/files` | GET | List workspace files |
| `read_file` | `/workspaces/:id/files/*path` | GET | Read file content |
| `write_file` | `/workspaces/:id/files/*path` | PUT | Write/overwrite file |
| `delete_file` | `/workspaces/:id/files/*path` | DELETE | Delete file |
| `replace_all_files` | `/workspaces/:id/files` | PUT | Replace all files atomically |
### Schedules
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_schedules` | `/workspaces/:id/schedules` | GET | List cron schedules |
| `create_schedule` | `/workspaces/:id/schedules` | POST | Create cron schedule |
| `update_schedule` | `/workspaces/:id/schedules/:id` | PATCH | Update schedule |
| `delete_schedule` | `/workspaces/:id/schedules/:id` | DELETE | Delete schedule |
| `run_schedule` | `/workspaces/:id/schedules/:id/run` | POST | Trigger schedule now |
| `get_schedule_history` | `/workspaces/:id/schedules/:id/history` | GET | Past run history |
### Channels (Social Integrations)
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_channels` | `/workspaces/:id/channels` | GET | List configured channels |
| `add_channel` | `/workspaces/:id/channels` | POST | Add Telegram/Slack/Lark channel |
| `update_channel` | `/workspaces/:id/channels/:id` | PATCH | Update channel config |
| `remove_channel` | `/workspaces/:id/channels/:id` | DELETE | Remove channel |
| `test_channel` | `/workspaces/:id/channels/:id/test` | POST | Test channel connectivity |
| `list_channel_adapters` | `/channels/adapters` | GET | Available platforms |
| `discover_channel_chats` | `/channels/discover` | POST | Auto-detect chats for bot token |
### Plugins
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_installed_plugins` | `/workspaces/:id/plugins` | GET | List installed plugins |
| `install_plugin` | `/workspaces/:id/plugins` | POST | Install plugin from source |
| `uninstall_plugin` | `/workspaces/:id/plugins/:name` | DELETE | Uninstall plugin |
| `list_available_plugins` | `/workspaces/:id/plugins/available` | GET | Plugins matching runtime |
| `list_plugin_registry` | `/plugins` | GET | Full plugin registry |
| `list_plugin_sources` | `/plugins/sources` | GET | Registered source schemes |
| `check_plugin_compatibility` | `/workspaces/:id/plugins/compatibility` | GET | Preflight check |
### Teams / Hierarchy
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
### Templates & Bundles
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_templates` | `/templates` | GET | Available templates |
| `import_template` | `/templates/import` | POST | Import template |
| `list_org_templates` | `/org/templates` | GET | Org template list |
| `import_org` | `/org/import` | POST | Import org template |
| `export_bundle` | `/bundles/export/:id` | GET | Export workspace bundle |
| `import_bundle` | `/bundles/import` | POST | Import workspace bundle |
### Tokens
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_tokens` | `/workspaces/:id/tokens` | GET | List workspace tokens |
| `create_token` | `/workspaces/:id/tokens` | POST | Create new bearer token |
| `revoke_token` | `/workspaces/:id/tokens/:id` | DELETE | Revoke specific token |
### Monitoring
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_activity` | `/workspaces/:id/activity` | GET | Activity log |
| `report_activity` | `/workspaces/:id/activity` | POST | Report agent activity |
| `list_events` | `/events` | GET | Platform event stream |
| `list_traces` | `/workspaces/:id/traces` | GET | LLM traces (Langfuse) |
| `session_search` | `/workspaces/:id/session-search` | GET | Search chat sessions |
### Approvals
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `create_approval` | `/workspaces/:id/approvals` | POST | Request approval |
| `get_workspace_approvals` | `/workspaces/:id/approvals` | GET | List approvals |
| `decide_approval` | `/workspaces/:id/approvals/:id/decide` | POST | Approve/reject |
| `list_pending_approvals` | `/approvals/pending` | GET | All pending approvals |
### Canvas
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `get_canvas_viewport` | `/canvas/viewport` | GET | Current viewport |
| `set_canvas_viewport` | `/canvas/viewport` | PUT | Set viewport position |
### Remote Agents
| MCP Tool | API Route | Method | Description |
|----------|-----------|--------|-------------|
| `list_remote_agents` | `/workspaces?runtime=external` | GET | List remote agents |
| `get_remote_agent_state` | `/registry/discover/:id` | GET | Remote agent status |
| `check_remote_agent_freshness` | `/registry/heartbeat` | POST | Check if agent is alive |
| `get_remote_agent_setup_command` | (local) | — | Get setup instructions |
## Authentication
Most routes require a bearer token:
```bash
curl -H "Authorization: Bearer <token>" http://localhost:8080/workspaces
```
Tokens are issued on workspace registration (`POST /registry/register`) or via the token management API (`POST /workspaces/:id/tokens`).
The MCP server handles auth automatically when configured with the correct `MOLECULE_URL`.
## Troubleshooting
| Issue | Fix |
|-------|-----|
| "Connection refused" | Check `MOLECULE_URL` points to running platform |
| "401 Unauthorized" | Token expired or revoked — create a new one |
| Tools not showing | Run `npx @molecule-ai/mcp-server` standalone to check for errors |
| Stale data | MCP server doesn't cache — check platform directly |
Reference in New Issue View Git Blame Copy Permalink