Guides
MCP Server Setup Guide Connect Claude Code, Cursor, or any MCP-compatible tool to Molecule AI. Full 87-tool reference for workspace management, agents, secrets, memory, schedules, channels, and plugins.
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.
The MCP server is published as @molecule-ai/mcp-server on npm.
npx @molecule-ai/mcp-server Add to your project's .mcp.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:
"MOLECULE_URL" : "https://your-org.moleculesai.app" Once configured, your MCP client should show 87 Molecule AI tools. Test with:
Variable Default Description MOLECULE_URLhttp://localhost:8080Platform API URL LOG_LEVELinfoLog level — trace, debug, info, warn, error, fatal (pino numeric levels: 10–60)
The MCP server emits structured JSON logs via pino . Each log entry includes level, time, pid, hostname, msg, and any extra fields passed as context.
When NODE_ENV != "production", logs are pretty-printed for human readability. In production the output is machine-parseable JSON.
Every log entry automatically includes MCP request context (tool name, request ID, workspace ID) when called from within a tool handler:
{ "level" : 30 , "time" : "2026-04-22T18:30:00.000Z" , "pid" : 1234 , "hostname" : "workspace-server" , "msg" : "rate limit hit" , "tool" : "list_workspaces" , "requestId" : "req_abc123" , "workspaceId" : "ws_xyz789" } Set LOG_LEVEL=debug (level 20) to trace all tool calls and request IDs. Set LOG_LEVEL=error (level 50) in CI to suppress informational output.
See molecule-mcp-server PR #6
MCP Tool API Route Method Description list_workspaces/workspacesGET List all workspaces get_workspace/workspaces/:idGET Get workspace details create_workspace/workspacesPOST Create a new workspace update_workspace/workspaces/:idPATCH Update workspace fields delete_workspace/workspaces/:idDELETE Delete a workspace restart_workspace/workspaces/:id/restartPOST Restart workspace container pause_workspace/workspaces/:id/pausePOST Pause workspace resume_workspace/workspaces/:id/resumePOST Resume paused workspace discover_workspace/registry/discover/:idGET Get workspace URL + agent card
MCP Tool API Route Method Description assign_agent/workspaces/:id/agentPOST Assign agent to workspace remove_agent/workspaces/:id/agentDELETE Remove agent replace_agent/workspaces/:id/agentPATCH Replace agent config move_agent/workspaces/:id/agent/movePOST Move agent to different workspace
MCP Tool API Route Method Description chat_with_agent/workspaces/:id/a2aPOST Send A2A message to agent async_delegate/workspaces/:id/delegatePOST Fire-and-forget delegation check_delegations/workspaces/:id/delegationsGET Check delegation status send_channel_message/workspaces/:id/channels/:channelId/sendPOST Send to social channel notify_user/workspaces/:id/notifyPOST Push notification to canvas list_peers/registry/:id/peersGET Find sibling/parent workspaces check_access/registry/check-accessPOST Check if two workspaces can communicate
MCP Tool API Route Method Description get_config/workspaces/:id/configGET Get workspace config.yaml update_config/workspaces/:id/configPATCH Update config fields get_model/workspaces/:id/modelGET Get configured LLM model
MCP Tool API Route Method Description list_secrets/workspaces/:id/secretsGET List workspace secret keys set_secret/workspaces/:id/secretsPOST Set a workspace secret delete_secret/workspaces/:id/secrets/:keyDELETE Delete a secret list_global_secrets/settings/secretsGET List global secrets set_global_secret/settings/secretsPUT Set a global secret delete_global_secret/settings/secrets/:keyDELETE Delete global secret
MCP Tool API Route Method Description memory_list/workspaces/:id/memoryGET List memory keys memory_get/workspaces/:id/memory/:keyGET Get memory value memory_set/workspaces/:id/memoryPOST Set memory key-value memory_delete_kv/workspaces/:id/memory/:keyDELETE Delete memory key search_memory/workspaces/:id/memoriesGET Full-text search memories commit_memory/workspaces/:id/memoriesPOST Commit HMA memory delete_memory/workspaces/:id/memories/:idDELETE Delete HMA memory
MCP Tool API Route Method Description list_files/workspaces/:id/filesGET List workspace files read_file/workspaces/:id/files/*pathGET Read file content write_file/workspaces/:id/files/*pathPUT Write/overwrite file delete_file/workspaces/:id/files/*pathDELETE Delete file replace_all_files/workspaces/:id/filesPUT Replace all files atomically
MCP Tool API Route Method Description list_schedules/workspaces/:id/schedulesGET List cron schedules create_schedule/workspaces/:id/schedulesPOST Create cron schedule update_schedule/workspaces/:id/schedules/:idPATCH Update schedule delete_schedule/workspaces/:id/schedules/:idDELETE Delete schedule run_schedule/workspaces/:id/schedules/:id/runPOST Trigger schedule now get_schedule_history/workspaces/:id/schedules/:id/historyGET Past run history
MCP Tool API Route Method Description list_channels/workspaces/:id/channelsGET List configured channels add_channel/workspaces/:id/channelsPOST Add Telegram/Slack/Lark channel update_channel/workspaces/:id/channels/:idPATCH Update channel config remove_channel/workspaces/:id/channels/:idDELETE Remove channel test_channel/workspaces/:id/channels/:id/testPOST Test channel connectivity list_channel_adapters/channels/adaptersGET Available platforms discover_channel_chats/channels/discoverPOST Auto-detect chats for bot token
MCP Tool API Route Method Description list_installed_plugins/workspaces/:id/pluginsGET List installed plugins install_plugin/workspaces/:id/pluginsPOST Install plugin from source uninstall_plugin/workspaces/:id/plugins/:nameDELETE Uninstall plugin list_available_plugins/workspaces/:id/plugins/availableGET Plugins matching runtime list_plugin_registry/pluginsGET Full plugin registry list_plugin_sources/plugins/sourcesGET Registered source schemes check_plugin_compatibility/workspaces/:id/plugins/compatibilityGET Preflight check
MCP Tool API Route Method Description expand_team/workspaces/:id/expandPOST Expand team node collapse_team/workspaces/:id/collapsePOST Collapse team node
MCP Tool API Route Method Description list_templates/templatesGET Available templates import_template/templates/importPOST Import template list_org_templates/org/templatesGET Org template list import_org/org/importPOST Import org template export_bundle/bundles/export/:idGET Export workspace bundle import_bundle/bundles/importPOST Import workspace bundle
MCP Tool API Route Method Description list_tokens/workspaces/:id/tokensGET List workspace tokens create_token/workspaces/:id/tokensPOST Create new bearer token revoke_token/workspaces/:id/tokens/:idDELETE Revoke specific token
MCP Tool API Route Method Description list_activity/workspaces/:id/activityGET Activity log report_activity/workspaces/:id/activityPOST Report agent activity list_events/eventsGET Platform event stream list_traces/workspaces/:id/tracesGET LLM traces (Langfuse) session_search/workspaces/:id/session-searchGET Search chat sessions
MCP Tool API Route Method Description create_approval/workspaces/:id/approvalsPOST Request approval get_workspace_approvals/workspaces/:id/approvalsGET List approvals decide_approval/workspaces/:id/approvals/:id/decidePOST Approve/reject list_pending_approvals/approvals/pendingGET All pending approvals
MCP Tool API Route Method Description get_canvas_viewport/canvas/viewportGET Current viewport set_canvas_viewport/canvas/viewportPUT Set viewport position
MCP Tool API Route Method Description list_remote_agents/workspaces?runtime=externalGET List remote agents get_remote_agent_state/registry/discover/:idGET Remote agent status check_remote_agent_freshness/registry/heartbeatPOST Check if agent is alive get_remote_agent_setup_command(local) — Get setup instructions
Most routes require a bearer token:
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.
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 High-volume log output Set LOG_LEVEL=error to suppress info/warn; in production, log output is JSON (machine-parseable)