AI tools and MCP
Orkestia Cockpit can act as a local MCP connector. An AI tool on the same computer starts orkestia-cockpit mcp, which speaks MCP over stdio and relays every tool call to the running app. The app makes the Orkestia call with your own session, in the organization you allowed for that tool. There is no token to copy and no separate sign-in.
This is the local alternative to the remote server, https://mcp.orkestia.dev/mcp, which hosted tools use and which signs in with your Orkestia account. See Connect an AI assistant for the remote server and Organization → Access for the one-click view of both.
| Local connector | Remote server | |
|---|---|---|
| Address | <app executable> mcp, started by the tool | https://mcp.orkestia.dev/mcp |
| Works for | Claude Code, Claude Desktop, Cursor, Codex, VS Code on this computer | claude.ai, Lovable, anything hosted or on another computer |
| Acts as | You, through the running app | You, through your sign-in or an API token |
| Needs the app open | Yes. If the app is signed out the call says so | No |
| Tools | The ten below, built around what you see in the app | The platform's workflow catalog (list_workflow_types, start_workflow…) |
Connect a tool
Settings → AI tools (also Connect AI Tools… in the command palette, and a button on Organization → Access) lists each supported tool found on the computer with its state:
| State | Meaning |
|---|---|
| Connected to this app | The tool's config has an orkestia entry that starts this app |
| Installed · not connected | Found, with no entry |
| Connected to another copy of this app (…) | The entry starts a different install. Update points it here, Disconnect removes it |
| Has its own "orkestia" entry, left as is | An orkestia entry that is not this app's, such as a remote server added by hand. The app never replaces or removes it. Rename or remove it first |
| Can't read | The config could not be parsed. Fix or simplify it first (comments are not supported) |
| Not found on this computer | Not installed |
Connect shows exactly what will change before anything is written: the tool's config file, a diff, where the previous file is kept (<file>.bak) and, for Claude Code, that the change is made with its own claude mcp add command. It adds one entry named orkestia and changes nothing else in the file; when nothing would change it says so and writes nothing. Disconnect removes only that entry. After connecting, restart the tool (or reload its MCP servers) to see Orkestia.
ORKESTIA_AITOOLS_HOME so tests never touch real configs. Release builds always use the real ones.The first call asks you
The first time a tool calls, the app shows Allow
wants to use Orkestia as in .
| Line in the sheet | Meaning |
|---|---|
| It can read your decisions, workflow runs, coding sessions and apps, search, and show things in this window | The scope of the ten tools |
| It can't approve or deny anything | Decisions are answered in the app, by you |
| It keeps acting in | The grant is pinned to the organization that was active when you allowed it |
Deny has the focus and nothing allows by keyboard. Closing the sheet is a Deny, and so is no answer within four minutes. A denial is remembered for two minutes so a tool that retries in a loop does not keep asking. One question is shown per tool at a time; extra calls wait for the same answer, and N more tools are waiting to ask is shown when several are queued. Signing out denies every open question.
Allowed tools
Allowed tools in Settings lists each grant: the tool, As
| Rule | Behavior |
|---|---|
| Per account | Grants belong to one Cockpit account. Another account signing in starts with none |
| Pinned organization | Calls keep acting in the organization of the grant after the app switches. If you leave that organization, calls are refused with a message to revoke the grant instead of moving to another organization |
| Tool identity | A grant is for the tool's name plus the program that started it (an app bundle, or an executable path with version folders folded), so it survives updates |
| Signed out | The call is refused: "Orkestia Cockpit is signed out. Open it, sign in, and try again." |
The tools
Every tool runs in the grant's organization. Answers are compact JSON: long values are shortened and anything that looks like a secret is left out. No tool can answer a decision.
| Tool | Does | Arguments |
|---|---|---|
whoami | The person signed in, the organization this tool was allowed for, and when it was allowed | none |
list_waiting_decisions | Decisions waiting for you, newest first, with the choices each offers | limit (up to 50), include_others to also list decisions addressed to someone else |
get_decision | One waiting decision: what is decided, why, facts and links, the recommended action and what each choice does. Says plainly when it is no longer waiting | decision_id |
list_recent_runs | Recent workflow runs, newest first | status (all, running, success, failed), since_hours (up to 168), workflow_type_prefix, limit |
get_run | One run by id: type, state, whether it finished and how, output | run_id |
list_coding_sessions | Your coding sessions, most recently active first, plus agent sessions running now | limit |
list_apps | The organization's apps: name, kind, address, ids | none |
search | What the Cockpit's search (⌘K) finds: decisions, agent sessions, coding sessions and chats, apps and tickets | query, limit |
open_in_app | Brings the window forward on an item | kind (decision, session, chat, app, section), id |
request_approval | Puts a waiting decision in front of you | decision_id, message (up to 280 characters) |
open_in_app opens a section by name: overview, decisions, activity, workflows, agents, coding, apps, runners, connections, organization or chat. Ids must be plain (letters, digits and _ . : @ -). If the app is working in another organization than the tool was allowed for, opening an item is refused and the tool is told to ask you to switch.
request_approval opens the decision in the app, sends a desktop notification titled answered: false and whether the decision is addressed to you. You answer in the app, and the tool can call get_decision later to see whether it is still waiting.
orkestia-cockpit:// links
The app registers the orkestia-cockpit:// scheme. A link only navigates: nothing is ever done because of a link.
orkestia-cockpit://open/<kind>/<id>
| Kind | Opens |
|---|---|
decision | That decision in Decisions |
session | That agent session in Activity |
chat | That chat or coding session |
app | That app in Apps (the id can be an app key such as site:<uuid>) |
section | A section: the names listed above |
Anything that is not open/<kind>/<id> with a known kind and a plain id is ignored. A decision notification from request_approval uses the same targets.
Troubleshooting
| You see | Do |
|---|---|
| The tool does not list Orkestia | Restart it or reload its MCP servers after Connect |
Orkestia Cockpit is signed out | Open the app and sign in |
| The tool "was allowed for | Revoke it in Settings → AI tools and let it ask again |
| It keeps being denied | Wait two minutes, or allow it from the sheet. A denial is remembered briefly |
| Nothing happens on the first call | The Allow sheet is waiting in the app window. Bring the app forward |
Organization — people, access and cost
Manage people and invitations, API tokens and the cost of an organization from Orkestia Cockpit — roles, one-time secrets, seats, usage, and where payment happens
App chats and shared chats
Read your apps' chat spaces inside Orkestia Cockpit — add a chat by link or from your organization, notifications and unread counts, taking your member seat — and share assistant chats with the people in your organization