MCP server

The Keanan MCP server brings your people ops into the AI tools you already use. It speaks the Model Context Protocol, so any MCP client can call it: Claude Desktop, Claude Code, Cursor, Windsurf and the growing list of others.

It never touches the database. Every tool calls the public API with your own API key, so your role, the workspace’s module flags, the audit trail and rate limits apply exactly as in the dashboard.

Set up in two minutes

1. In your workspace open Settings, Developers (or Time portal, API and assistants) and create a personal key. Pick the scopes you want the assistant to have; read only is a fine start.
2. Add the server to your client. The Developers page shows the snippets with your workspace address filled in.

Claude Desktop or Cursor (claude_desktop_config.json / mcp.json):

{
  "mcpServers": {
    "keanan": {
      "command": "uvx",
      "args": ["keanan-mcp"],
      "env": {
        "KEANAN_URL": "https://acme.keanan.app/api/v1",
        "KEANAN_API_KEY": "kn_live_..."
      }
    }
  }
}

Claude Code:

claude mcp add keanan -e KEANAN_URL=https://acme.keanan.app/api/v1 -e KEANAN_API_KEY=kn_live_... -- uvx keanan-mcp

Hosted endpoint. Every workspace also serves the server over Streamable HTTP at https://acme.keanan.app/mcp/. Clients that support remote servers connect there with the header Authorization: Bearer kn_live_...; nothing to install.

uvx comes with uv. If you prefer pip: pip install keanan-mcp and use keanan-mcp as the command.

What you can ask

Read tools:

Tool	Try asking
whoami	“Which Keanan workspace am I connected to?”
get_time_off_balance	“How many vacation days do I have left?”
list_absences	“Show my pending requests.”
whos_out	“Who is out next week?”
list_time_entries	“What did I track this week?”
my_time_report	“Am I over or under my hours this month?”
clock_status	“Is my clock running?”
list_projects_and_services	“Which projects can I book time on?”
list_pending_approvals	“What is waiting for my approval?” (managers)
get_payslips, get_contracts	“When was my last payslip?”
search_help_center	“How does the parental leave policy work here?”
list_workspace_options	“Which expense categories exist?”

Write tools preview first and only act when called again with confirm=true, which the assistant does after you agree:

Tool	Try asking
request_time_off	“Request 7 to 8 September off as vacation.”
approve_absence, deny_absence, approve_expense	“Approve Shuri’s request.”
clock_start, clock_stop	“Clock me in on the relaunch project, development.”
add_time_entry	“Log 9 to 11:30 today on the driver portal.”
submit_expense	“Submit a 12.50 taxi expense.”

Two prompts ship with the server: weekly_timesheet_summary and whos_out_standup.

Safety

• The assistant can only do what your key’s scopes allow. One click on the Developers page turns a key read only.
• Every write shows a preview first. Nothing is sent until the assistant calls the tool again with confirm=true.
• Writes appear in the audit trail as mcp:<key prefix>.
• Revoking the key cuts the assistant off immediately.

Self hosting the server

The hosted endpoint is the mcp service in docker-compose.prod.yml, routed by Caddy at /mcp*. It reads KEANAN_URL (the internal backend URL) and takes the API key from each request’s Authorization header. To run it elsewhere: keanan-mcp --transport http --host 0.0.0.0 --port 8765.