MavenOS API

Connect with MCP

MavenOS runs an MCP (Model Context Protocol) server at `/api/mcp`. It uses MCP over Streamable HTTP and is stateless: every request is a single `POST` with a JSON-RPC message, and every answer is a single JSON body. There are no sessions and no streams, and `GET` and the other methods return `405`. It supports `initialize`, `ping`, `tools/list` and `tools/call`. Batches are not supported.

The endpoint is on your MavenOS address: `https://os.mavenx.co/api/mcp`. The Assistant page in MavenOS shows the exact address for your workspace.

Make an Assistant key

Open the Assistant page in MavenOS and create a key. Give it a name, choose how long it lasts, and decide whether to turn on Allow changes. Allow changes is off by default and is not available to viewers. The key is shown once, when you create it, so copy it straight away.

A workspace owner can turn Assistant keys off for a role. When that happens, keys made by people in that role stop working.

Add MavenOS to Claude

Send the key as a Bearer token in the `Authorization` header. In Claude Code, run this in a terminal with your own address and key:

claude mcp add --transport http mavenos https://os.mavenx.co/api/mcp \
  --header "Authorization: Bearer YOUR_ASSISTANT_KEY"

Cursor and other clients that accept a remote server with headers use the same address and header:

{
  "mcpServers": {
    "mavenos": {
      "url": "https://os.mavenx.co/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_ASSISTANT_KEY" }
    }
  }
}

Claude Desktop starts remote servers through `mcp-remote`. Keep the key in an environment variable so the space in `Bearer ...` is not split:

{
  "mcpServers": {
    "mavenos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://os.mavenx.co/api/mcp", "--header", "Authorization:${MAVENOS_AUTH}"],
      "env": { "MAVENOS_AUTH": "Bearer YOUR_ASSISTANT_KEY" }
    }
  }
}

To check the connection from a terminal, call `initialize`. A wrong key fails here, at connect time:

curl -X POST https://os.mavenx.co/api/mcp \
  -H "Authorization: Bearer YOUR_ASSISTANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}'

The server accepts protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Ask Claude something like "What is on my plate today?" once it is connected.

What a key can see

Reads run as the key's person under their own access rules. A member sees their own work, and Sales only if they have it. A private task, its comments and the notes about it stay hidden from everyone except the people the app shows them to. A record the person cannot see is reported as not found.

Money is shown only to owners, admins and finance. For anyone else, deal amounts come back as `null` (and the pipeline shows counts without totals), the invoice list is empty, and a request that sets deal amounts is refused.

A key cannot read HR records, pay, write-ups, reviews, incidents, contracts, private notes or free-text notes, and it cannot change HR, pay or money. It cannot reply to customers, send quotes or email, publish, or approve anything. A tool for a part of MavenOS that is switched off in your workspace is left out of the tool list.

Changes are available only when the key was created with Allow changes and its person is not a viewer or otherwise read-only. Nothing can be deleted except a project phase, and only after the person confirms. Articles are only ever created and edited as drafts. Each change is logged against the key.

Read tools

These tools only read. Lists return at most `limit` rows (1 to 50, default 15) with `has_more` and `next_cursor`; pass `next_cursor` back as `cursor` for the next page. The older short lists (marked below) take only `limit`.

Money tools

These tools read financial data. They return data only to people who can read Finance in your workspace: owners, admins and finance by default, and anyone who has been given Finance read access. For everyone else the answer is empty or says the figures are not available.

Write tools

These tools appear only for a key made with Allow changes. Each accepts an optional `request_id` (a UUID you make up): send the same one again and the change is made once, with the first answer returned. The person's role and the app's own rules decide each call, and none of these tools deletes anything except `delete_project_phase`.

Limits and errors

A tool that fails returns a normal JSON-RPC answer with `isError: true` and a plain sentence: access refused, not found, a part of MavenOS switched off, an invalid argument, or a change refused (not allowed, workspace read-only, or too many changes). When a change cannot be confirmed, check whether it was made before you retry, or send it again with the same `request_id`.

Using the REST API

REST API v2 lets a script or another system read and change tasks and projects, list people, and read and upsert Sales companies, contacts and deals in one workspace. Every call acts as one workspace member (the person who made the key, or a service person made for it), and that person's role decides what it can do. There are no deletes, and nothing about HR is returned. The endpoint reference on this page is generated from MavenOS's own OpenAPI description.

Paths are scoped to a workspace: `https://os.mavenx.co/api/v2/YOUR_WORKSPACE/...`. The API access page in MavenOS shows the exact address with your workspace name filled in.

export MAVENOS_API_KEY="YOUR_API_KEY"
export MAVENOS_ROOT="https://os.mavenx.co/api/v2/YOUR_WORKSPACE"

# Who is this key?
curl -H "Authorization: Bearer $MAVENOS_API_KEY" "$MAVENOS_ROOT/me"

# Create a task
curl -X POST "$MAVENOS_ROOT/tasks" \
  -H "Authorization: Bearer $MAVENOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Follow up with the client"}'

REST keys and scopes

API keys are separate from Assistant keys. Owners and admins create them under Settings, API access. A key looks like `mos_<prefix>_<secret>` and is shown once. Send it as `Authorization: Bearer ...`; keys in the address are not accepted. A key works only in its own workspace.

Work calls use the `work:read` and `work:write` scopes. Sales calls use `crm:read` and `crm:write`. Writes also need the API access add-on. Workspaces that require two-step sign-in refuse API keys. Deal amounts are returned and accepted only when the key acts as an owner, admin or finance person.

Pagination, idempotency and rate limits

Lists answer `{ "data": [...], "next_cursor": ... }`. Use `limit` (default 50, at most 100) and pass `next_cursor` back as `after`. The cursor is opaque. Many lists also accept `updated_since`.

Every `POST` and `PATCH` needs an `Idempotency-Key` header: a UUID, or 8 to 64 letters, digits, underscores or hyphens. Repeat a call with the same key within 24 hours and nothing is written twice; you get the first answer back with `Idempotent-Replayed: true`. Reusing a key for a different call or body returns `422 idempotency_conflict`. Optionally send `MavenOS-Version: 2026-10-21`; it is the only accepted value.

Each key has one rate class. These are hard caps with no overage. The daily count resets at 00:00 UTC. Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a `429` carries `Retry-After` in seconds. JSON bodies are limited to 64 KB (32 KB on the Sales calls).

REST errors

Errors have the shape `{ "error": { "code": "...", "message": "...", "request_id": "..." } }`, with a `fields` list on `bad_request` that names each input and its problem (`required`, `invalid` or `unknown_field`). Quote the `request_id` when you ask for help.

Webhooks

With the API access add-on, MavenOS can post a signed JSON message to an https address you choose when something happens. Owners and admins manage webhooks under Settings, Integrations; finance can subscribe only to the money events. Events: `lead.created`, `contact.created`, `deal.created`, `deal.stage_changed`, `deal.won`, `deal.lost`, `task.completed`, `ticket.created`, `invoice.paid` and `invoice.overdue`, plus `webhook.test` from the Send test button.

Each delivery carries `MavenOS-Event-Id`, `MavenOS-Event-Type`, `MavenOS-Delivery-Id`, `MavenOS-Timestamp` and `MavenOS-Signature` (for example `v1=...`, an HMAC-SHA256 over the timestamp and body, keyed with the signing secret shown once when you create the webhook). Only the timestamp and body are signed, so read the event id and type from the body.

Delivery is at least once, so deduplicate on the `id` in the body. A `2xx` answer within 8 seconds is success. Failed attempts are retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then dropped after the eighth attempt. A `410` answer switches the webhook off at once.