The MCP server

What it is

One endpoint that speaks JSON-RPC 2.0 over a single POST. Point an MCP client at it with a workspace API key and the employees in that workspace appear as tools the client can call.

This is the inbound direction: other software asking your hire to do something. It is separate from the connections your hire uses to reach your apps, which are set up in the console.

https://employees.sanafai.com/api/mcp
Authorization: Bearer emp_<workspace>_<secret>

The tools

Four, and they compose in the obvious order: find the employee, give it something to do, read what it said, and check what it has been doing.

1. 1

   list_employees

   The AI employees in this workspace: id, name, and whether each is live. The id is what every other tool takes.

2. 2

   ask_employee

   Give an employee a task or a question in plain language. Returns the chat id and run id. The employee works asynchronously and may pause for its manager approval, so this does not block.

3. 3

   get_reply

   Read a chat with an employee: every message so far, newest last. This is how you collect the answer after ask_employee.

4. 4

   list_work

   What an employee has done recently, from its work log. Takes an optional limit, twenty by default and fifty at most.

Notifications

A JSON-RPC notification, meaning a message with no id, is answered with 202 and an empty body. That is what the transport expects; answering anything else would be a protocol violation.

Errors

An unauthorised request comes back as a JSON-RPC error with code -32001 and HTTP 401. A body that is not valid JSON is a parse error, code -32700, with HTTP 400.

Endpoint reference