The MCP server

Your enterprise's own MCP server, for agents you run: what it is, what it can do, and what a token lets it reach.

What it is

Zero Human OS runs an MCP server that any MCP client can connect to. Point an agent you run at it, with an API token, and the agent can see what your enterprise is doing: its runs, what is blocked, and which decisions are waiting on you.

What Detail
Endpoint https://mcp.zerohuman.com/v1/mcp
Transport Streamable HTTP, stateless: every request is a POST, answered in JSON. There is no session.
Authentication Authorization: Bearer zhos_…, an API token from Settings → API tokens in the portal
What a token reaches What its scopes allow, exactly as on the API (Authentication), in the enterprise it was created in
Tools Reads over runs, blockers, waiting gates, the Waiting list and KPIs; writes of KPI readings and targets; deciding a waiting gate; finishing and restarting Waiting work; and chat with a member. The complete list, generated from the server's own definitions, is Tools
Health https://mcp.zerohuman.com/v1/health, with no token

To connect Claude Code, Claude Desktop or another client, see Connect a client.

What it can do

Family Tools Scope What they read
Runs os.list_runs, os.get_run runs:read Runs, newest first, by status, by task, or only those in progress; one run's status, input and last eight events.
Blockers os.list_blockers blockers:read What is stopping work now, as the Blockers page shows it.
Gates os.list_open_gates, os.decide_gate gates:read, gates:write Every gate waiting on a decision: the run, the tool call it holds, and who decides; and a write: decide one, as its card in Needs you does.
Waiting os.list_waiting, os.finish_waiting, os.restart_waiting runs:read, runs:write Open work nothing is working on, as the Waiting page shows it; and two writes: mark a row's work finished, and restart it at a step of its pipeline.
KPIs kpi.list_readings, kpi.record_reading kpis:read, kpis:write A KPI's reading history; and a write: append a new reading to a signed-off KPI.
Chat os.chat_list, os.chat_read, os.chat_open, os.chat_write chats:read, chats:write Your chats with members and what was said in one; and two writes: open a chat with a member, and write to them. The member replies in the same call.
Your mail os.my_mail_list, os.my_mail_read, os.my_mail_attachment, os.my_mail_actions, os.my_mail_set_label, os.my_mail_set_handled, os.my_mail_set_many, os.my_mail_reply, os.my_mail_send, os.my_mail_forward, os.my_mail_delete, os.my_mail_start_action, os.my_mail_schedule_action, os.my_mail_unschedule_action, os.my_mail_signature, os.my_mail_signature_set, os.my_mail_addresses, os.my_mail_address_signature_set mail:read, mail:write Your own mailbox (People and access): the list, one message with its bodies, a file on it, the one-click buttons your inbox offers, your signature, and your extra addresses with each one's own signature; and the writes: label a message, record where it stands, make one change on many at once, reply to one, forward one, send a new one from your own address with no approval step, delete one for good, press one of the buttons, which starts that task over your own mailbox, or put one on a cadence of your own and stop it, and set or clear your signature or one address's. Only for an app you connected as yourself: a token is nobody and has no mailbox.
A member's mailbox os.member_mailbox_actions members:read The one-click buttons a member's mailbox offers (Members and inboxes): the tasks that declare a mailbox action and run as a role the member holds. Start one with os.start_task, with the message's id as emailId for a button on one mail.

Every tool is listed to every token. Each tool's description ends with the scope it needs, so an agent knows before it calls. Tools is the complete list, with each tool's arguments; it is generated from the definitions the server serves, so it cannot drift from them.

What it cannot do

  • Run your enterprise. Its writes record KPI readings and targets, write to a member in chat, finish or restart work on the Waiting list, and decide a waiting gate as its card in Needs you does. No tool cancels a run or retries one on Blockers: that is done in the portal or over the API. A member you write to in chat can start a task it holds, as it can for anyone it talks to.
  • Manage API tokens. No tool does, and the API refuses any token that tries.
  • Reach another enterprise. A token acts for the enterprise it was created in. Another enterprise's run is "not found".
  • Offer resources or prompts. It offers tools only.
  • Tell your agent when something changes. It never sends a message unasked. The agent asks again.

How it relates to the API

The MCP server is a thin layer over the API. Each tool is one API route. Calling a tool makes that one request with your token, and the API's answer comes back as the tool's result. So:

  • the token's scopes decide what a tool can do, exactly as they would for a script calling the API;
  • a refusal is the API's own, in its own words (Errors);
  • the token's Last used in the portal moves when a tool call reaches the API.

Connecting and listing tools do not reach the API. They only need a bearer token to be present, so a client connects even with a revoked or mistyped token, and fails on its first tool call. To know a token works, call a tool.

Sign in instead of a token

An MCP client that supports sign-in, such as a custom connector in Claude or ChatGPT, connects by signing in with Zero Human instead of holding a token: you choose the enterprise, the member it acts as and what it may do, and revoke it later under Settings → Connected apps. See Connected apps. Signing in is also the only way an app reaches your own mail: a token acts for the enterprise, and your mailbox is yours.

Planned

Tools that change things

The MCP server will offer more of the OS's own tools, including ones that change things. Each will be one API route behind the scope that route needs, so a token's scopes will govern them as they govern the API.

  • Starting a task, the OS's own tasks included. An agent will list the tasks a member holds and start one. The OS's own tasks are among them, the same in every enterprise: ask for a new team, role, member or task, or a change to one, and the OS designs it and puts it to you to sign off, as it does from chat. The agent will read the run and the decision it waits on, and decide it when it acts for a person who may.
  • Changing roles, teams and members directly. The same writes the portal's pages make, under the scopes that already govern them on the API, with no plan and no sign-off.