Core Features
Orca MCP Server
Connect AI agents directly to Orca via MCP
The Orca MCP server lives at https://api.orca.marcofaul.de/mcp. The versioned URL (/api/v2/agent/mcp) keeps working for existing configurations; the legacy v1 server (/api/agent/mcp) has been removed and returns 410 Gone.
Overview
Orca provides an MCP (Model Context Protocol) server. AI agents use it to work with your tasks, workspaces, terminals, pages, automations, and hosts.
Capabilities
See Available Tools for every tool, grouped by category.
Setup
CLI Options
claude mcp add orca --transport http https://api.orca.marcofaul.de/mcpManual Configuration
Or configure each client by hand:
Add a .mcp.json to your project root. Claude Code auto-discovers this file and handles OAuth authentication.
{
"mcpServers": {
"orca": {
"type": "http",
"url": "https://api.orca.marcofaul.de/mcp"
}
}
}Authentication
The MCP server uses OAuth 2.1. On first connect, your browser asks you to authorize the connection. The token is scoped to your active organization.
API Key Authentication
For headless environments, CI, and scripts where browser OAuth is not practical, use an API key.
Generating an API key:
- Open the Orca desktop app
- Go to Settings > API Keys
- Click Create API Key
- Copy the key (it starts with
sk_live_). It is shown only once.
Using the API key:
Pass the API key as a Bearer token in the Authorization header:
Authorization: Bearer sk_live_your_api_key_hereMCP clients that support custom headers can use this directly. For Claude Code, set the header in your .mcp.json:
{
"mcpServers": {
"orca": {
"type": "http",
"url": "https://api.orca.marcofaul.de/mcp",
"headers": {
"Authorization": "Bearer sk_live_your_api_key_here"
}
}
}
}API keys grant full access to your organization. Never commit them. Use environment variables or a secrets manager in CI.
When to use which method:
| Method | Best for |
|---|---|
| OAuth 2.1 | Interactive use: Claude Desktop, Claude Code, Cursor |
| API Key | Headless/CI: scripts, automation, pipelines |
Available Tools
Tasks
| Tool | Description |
|---|---|
tasks_list | List tasks with optional filters (status, priority, assignee, free-text search) |
tasks_get | Get one task by UUID or slug |
tasks_create | Create a task in the active organization |
tasks_update | Update fields on an existing task |
tasks_delete | Soft-delete a task by UUID |
tasks_statuses_list | List the organization's task statuses (for tasks_create/tasks_update statusId) |
Workspaces
| Tool | Description |
|---|---|
workspaces_list | List workspaces on a host (get the hostId from hosts_list) |
workspaces_create | Create a workspace on a host, optionally launching agents with per-launch model and effort overrides |
workspaces_update | Update fields on a workspace on its host |
workspaces_delete | Delete a workspace by UUID on its host |
Agents
| Tool | Description |
|---|---|
agents_list | List agents configured on a host |
agents_create | Create (launch) an agent session with optional per-launch model and effort overrides |
Terminals
| Tool | Description |
|---|---|
terminals_create | Create a terminal session in a workspace, optionally running a command |
terminals_list | List terminal sessions in a workspace |
terminals_send | Write text into a running terminal (presses Enter by default) |
terminals_read | Read the terminal screen as plain text (current screen plus recent scrollback) |
terminals_close | Close a terminal session and kill its process |
Pages
Orca Pages publish agent output as a shareable URL. pages_publish takes a self-contained HTML document. Every publish creates a new version; nothing is overwritten.
| Tool | Description |
|---|---|
pages_list | Search and paginate pages, optionally scoped to one workspace |
pages_get | Get one page's metadata by id or slug (title, visibility, URL, served version) |
pages_versions | List a page's version history, newest first |
pages_pull | Get a download URL for a page's HTML, plus that version's metadata |
pages_storage | Read what viewers stored on a page, by key, scope or per person |
pages_storage_set | Write a value under a key in a page's storage, as you |
pages_storage_remove | Remove a value under a key in a page's storage, as you |
pages_publish | Publish an HTML document (passed inline, not as a path) and get its shareable URL |
pages_comments_list | List comment threads on a page, with replies and resolved state |
pages_comments_reply | Post a reply into a comment thread |
pages_comments_resolve | Mark a comment thread resolved, or reopen it |
pages_list returns { items, nextCursor }, ordered newest-created first.
Pass search to match title, slug, or description, limit for 1–200 rows
(default 50), and the returned nextCursor as cursor to continue. Keep
fetching until nextCursor is null. scope accepts all (default), team
for shared pages, or mine for your private pages.
pages_publish accepts visibility: "just_me", "org" (the default for new
pages), or "everyone" for anonymous read-only access. Pass workspaceId and
entryPath together to link the page to a workspace. Both are optional;
outside a workspace, save the returned id and pass it as pageId when
publishing updates. Otherwise each publish creates a separate page.
Automations
| Tool | Description |
|---|---|
automations_list | List automations the calling user owns |
automations_get | Get one automation's metadata (prompt body omitted) |
automations_get_prompt | Fetch the full markdown prompt for one automation |
automations_create | Create an automation that runs on an RFC 5545 RRULE schedule, on event triggers, or both |
automations_update | Update an automation (name, schedule, triggers, agent, host); triggers replaces the whole set. Use automations_set_prompt to change the prompt |
automations_set_prompt | Replace the full markdown prompt body |
automations_pause | Pause an automation (its schedules and event triggers stop firing) |
automations_resume | Resume a paused automation |
automations_run | Dispatch an automation immediately, without waiting for a schedule or event |
automations_trigger_options | List the values an event trigger can filter on (channels, repositories, teams, ...) |
automations_logs | List recent runs for an automation |
automations_archive | Archive an automation |
automations_unarchive | Restore an archived automation, paused |
automations_delete | Permanently delete an archived automation |
Projects
| Tool | Description |
|---|---|
projects_list | List projects (checked-out repos) on a host (get the hostId from hosts_list) |
Hosts
| Tool | Description |
|---|---|
hosts_list | List the hosts (registered machines) you have access to |
Organization
| Tool | Description |
|---|---|
organization_members_list | List members of the active organization |
Chat Integration
In the built-in chat panel, use the /mcp slash command to see your workspace's configured MCP servers: their names, transport type (local/remote), and current state (enabled/disabled/invalid). This reads from your workspace MCP config (.mastracode/mcp.json, .amp/settings.json, or .mcp.json).
Example Usage
Once connected, ask your agent to:
- "Create a task for fixing the login bug"
- "List all my assigned tasks"
- "Create a workspace for the auth feature on my MacBook"
- "Schedule a daily automation that triages new Linear issues at 9 a.m."
- "Pause the nightly cleanup automation"
- "Show me the last 10 runs of my Linear triage automation"
- "Answer the two threads handed to me on the launch-plan page"