Skip to main content
The orchagent MCP server lets any Model Context Protocol client interact with your orchagent account. Add it to Claude Desktop, Claude Code, or Cursor and you can run agents, manage tasks, send messages, and monitor runs — all from natural language.
The MCP server is a thin adapter. Every tool call maps directly to a gateway API endpoint. Auth, rate limiting, and validation are all handled by the gateway.

​
Install

npm install -g @orchagent/mcp-server
Or use npx (no install needed) — see setup below.

​
Setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
  "mcpServers": {
    "orchagent": {
      "command": "npx",
      "args": ["@orchagent/mcp-server"],
      "env": {
        "ORCHAGENT_API_KEY": "sk_..."
      }
    }
  }
}
Restart Claude Desktop after saving.
Get your API key from orchagent.io/settings/api-keys.

​
Environment Variables

VariableRequiredDescription
ORCHAGENT_API_KEYYesYour orchagent API key
ORCHAGENT_GATEWAY_URLNoOverride gateway URL (default: https://api.orchagent.io)

​
Available Tools

The MCP server exposes 13 tools across 5 categories.

​
Agents

ToolDescription
orchagent_list_agentsList all agents in your account. Optional workspace_id filter.
orchagent_run_agentExecute a deployed agent in a cloud sandbox. Params: org, agent, version, input.

​
Tasks

ToolDescription
orchagent_list_tasksList tasks. Filter by status, project, priority, overdue.
orchagent_create_taskCreate a task with title, description, due_date, project, priority.
orchagent_update_taskUpdate any field on a task. Use status: "done" to complete it.
orchagent_delete_taskPermanently delete a task.

​
Messages

ToolDescription
orchagent_list_messagesList messages from agents. Filter by level or agent_name.
orchagent_send_messageSend a message to the feed. Set title, body, level (info/success/warning/error).

​
Schedules

ToolDescription
orchagent_list_schedulesList scheduled agent runs in a workspace.
orchagent_create_scheduleCreate a cron or webhook schedule for an agent.
orchagent_trigger_scheduleManually trigger a scheduled run immediately.

​
Runs

ToolDescription
orchagent_list_runsList recent agent runs. Filter by agent_name, status.
orchagent_get_run_logsGet stdout, stderr, and exit code for a specific run.

​
Examples

Once the MCP server is configured, you can use natural language in your MCP client:

​
Run an agent

“Run the morning-brief agent”
Claude calls orchagent_run_agent with your org, agent name, and version. The agent executes in a cloud sandbox and returns the result.

​
Manage tasks

“Show me my overdue tasks”
Claude calls orchagent_list_tasks with status: "open" and overdue: true.
“Add a task: review PR #42, due Friday, high priority”
Claude calls orchagent_create_task with the parsed title, due date, and priority.

​
Schedule agents

“Schedule security-scanner to run every day at 6am London time”
Claude calls orchagent_create_schedule with cron_expression: "0 6 * * *" and timezone: "Europe/London".

​
Send messages

“Send a success message to my feed saying the deploy finished”
Claude calls orchagent_send_message with level: "success".

​
Use with Claude Desktop Scheduled Tasks

Claude Desktop supports scheduled tasks that run prompts on a cron. Combined with the orchagent MCP server, you can create scheduled prompts that trigger cloud agent execution:
  1. Configure the orchagent MCP server in Claude Desktop (see setup above)
  2. Create a scheduled task in Claude Desktop with a prompt like: “Run my morning-brief agent and send me the summary”
  3. Claude Desktop runs the prompt on schedule, calling orchagent_run_agent via MCP
  4. The agent runs in orchagent’s cloud sandbox — no need to keep your laptop open
This bridges local scheduling (Claude Desktop) with cloud execution (orchagent).

​
Next Steps

Tasks

Learn about the task system

Messages

How agent messages work

Scheduling

Set up cron and webhook schedules

SDK Reference

Full SDK documentation