catapa-mcp

An MCP server exposing CATAPA's HR & payroll APIs as tools, built on top of the official catapa (public, OAuth2) and catapa-private (private, session-authenticated) Python SDKs.

What it exposes

• Public API tools (catapa_*) -- one MCP tool per resource operation in the catapa SDK, generated automatically at startup by walking the SDK's resource tree (catapa.resource_registry). This covers ~190 resources (employees, payroll, time management, analytics, ...) and several hundred operations in total. Tool names follow the SDK's own path, e.g. catapa_core_employees_list, catapa_core_cost_centers_create.

• Private API tools (catapa_private_*) -- the catapa-private SDK is a thin, session-authenticated HTTP client rather than a per-endpoint client, so it's wrapped 1:1 as seven generic tools: catapa_private_get, catapa_private_post, catapa_private_put, catapa_private_patch, catapa_private_delete, catapa_private_get_all (auto-paginating), and catapa_private_session_status. See the private API docs for available paths.

Each half is independent -- set up credentials for one, both, or neither (an unconfigured half is simply skipped, with a warning logged to stderr).

OAuth login (recommended)

catapa-private has no OAuth of its own -- only a direct username/password login -- but its client also accepts a static bearer token, and CATAPA's public API already has a real, browser-redirect OAuth2 authorization-code flow. Setting CATAPA_MCP_AUTH_MODE=oauth uses that flow to authenticate both clients with a single login: the first time the server starts (or whenever the cached token can't be silently refreshed), it opens your browser to CATAPA's hosted login page, waits for the redirect on a local loopback server, exchanges the resulting code for an access/refresh token pair, and caches it to ~/.catapa-mcp/oauth-token.json for future launches. See src/catapa_mcp/oauth.py.

Related MCP server: MCP App with Authentication

Install

pip install -e .
# or: uv sync

Requires Python 3.11-3.13.

Configure

Copy .env.example to .env and fill in credentials, or set the environment variables directly wherever the server runs (e.g. in your MCP client's config).

# Recommended: a single interactive OAuth login for both APIs (opens your browser)
CATAPA_MCP_AUTH_MODE=oauth
CATAPA_CLIENT_ID=...
CATAPA_CLIENT_SECRET=...

# Or, per-API credentials:

# Public API: either an access token, or OAuth2 client credentials
CATAPA_TENANT=your-tenant
CATAPA_ACCESS_TOKEN=...
# or
CATAPA_CLIENT_ID=...
CATAPA_CLIENT_SECRET=...

# Private API: either an access token, or username/password (session auth)
CATAPA_PRIVATE_ACCESS_TOKEN=...
# or
CATAPA_PRIVATE_USERNAME=...
CATAPA_PRIVATE_PASSWORD=...

See .env.example for the full list, including CATAPA_MCP_INCLUDE / CATAPA_MCP_EXCLUDE for scoping the public API's tool count down to specific resource namespaces (e.g. CATAPA_MCP_INCLUDE=core.employees,timemanagement), and CATAPA_MCP_ENABLE_PUBLIC / CATAPA_MCP_ENABLE_PRIVATE for turning either half off entirely.

Run

catapa-mcp
# or
python -m catapa_mcp

The server speaks MCP over stdio.

Claude Desktop / Claude Code

Add to your MCP client's config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "catapa": {
      "command": "catapa-mcp",
      "env": {
        "CATAPA_TENANT": "your-tenant",
        "CATAPA_ACCESS_TOKEN": "...",
        "CATAPA_PRIVATE_ACCESS_TOKEN": "..."
      }
    }
  }
}

Remote deployment (Vercel, private API only, multi-tenant)

src/catapa_mcp/remote/ is a separate, Streamable-HTTP MCP server for deploying to Vercel so multiple people/orgs can connect without each running the server locally. It intentionally only exposes the catapa_private_* tools -- it does not port the public API's ~300 generated tools.

Unlike the stdio server (one shared login, one local token cache), each connecting user authenticates with their own CATAPA account:

1. The MCP client (Claude) starts an OAuth flow against this deployment.

2. This deployment redirects the user's browser to CATAPA's real, hosted login page (there's no separate "private API OAuth" -- CATAPA only has OAuth on the public API side, so that's what's used; see src/catapa_mcp/remote/oauth_provider.py).

3. Once CATAPA redirects back, the resulting CATAPA access/refresh token is sealed (encrypted, via src/catapa_mcp/remote/crypto.py) directly into the MCP token handed back to the client -- there is no per-user token table.

4. Every subsequent tool call decrypts that request's own token to build a CatapaPrivate client scoped to that specific user (src/catapa_mcp/remote/private_tools.py), so different users' requests never share credentials.

The only persistent storage needed is for OAuth client registrations and the few-seconds-lived login handshake (src/catapa_mcp/remote/store.py, backed by Upstash Redis via the Vercel Marketplace integration). Storage is behind the TokenStore abstract interface specifically so a future move to Postgres/MariaDB/etc. is a new subclass wired into build_token_store(), not a rewrite.

Deploying

1. Attach an Upstash Redis store to the Vercel project (Marketplace tab) -- this sets UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN automatically.

2. Set these environment variables in the Vercel project:

   MCP_SERVER_URL=https://your-app.vercel.app   # this deployment's own public URL
   CATAPA_CLIENT_ID=...
   CATAPA_CLIENT_SECRET=...
   MCP_TOKEN_ENCRYPTION_KEY=...   # generate: python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

   MCP_TOKEN_ENCRYPTION_KEY decrypts every connected user's CATAPA credentials -- treat it as a master secret, and don't rotate it casually (rotating logs everyone out). CATAPA_BASE_URL, CATAPA_AUTHORIZATION_URL, and CATAPA_PRIVATE_BASE_URL are optional overrides with the same defaults as the stdio server.

3. Deploy. api/index.py exposes the ASGI app Vercel's Python runtime auto-detects; vercel.json routes all paths to it; .python-version pins Python 3.12, since Vercel's Python runtime only supports 3.12+.

4. Visit https://your-app.vercel.app/ in a browser -- a status page confirms the deployment is actually up (version, the MCP endpoint URL, a link to the OAuth discovery document, and the list of exposed tools) before you try connecting a client to it.

Vercel gotcha (confirmed, not hypothetical): Vercel's zero-config Python detection bundles the whole project into a single function, but mounts it at the fixed path /python -- not at /api/index (the file-based path you'd expect from api/index.py). vercel.json's rewrites destination must point at /python; pointing it at /api/index (a very natural first guess) silently 404s on every route, since the deployment still reports "Ready" -- there's no build error to notice. If a fresh deploy 404s everywhere, check the deployment's Resources tab for the actual Function Path column and match rewrites to it.

Other caveats, since this hasn't been fully tested against real CATAPA infrastructure:

• CATAPA_AUTHORIZATION_URL's default (https://accounts.catapa.com/oauth2/authorize) is an unverified guess mirroring CATAPA's dev-environment naming; override it if wrong.

Connecting a client

The deployment speaks standard MCP Streamable HTTP with OAuth 2.1 (dynamic client registration, authorization-code flow) at https://your-app.vercel.app/mcp -- any compliant MCP client can add it as a remote connector. Two concrete examples:

Claude (claude.ai web or Claude Desktop): Settings -> Connectors -> Add custom connector -> paste https://your-app.vercel.app/mcp -> Connect. Claude discovers OAuth support automatically from /.well-known/oauth-authorization-server and opens a browser to CATAPA's login page.

Claude Code (CLI):

claude mcp add --transport http catapa https://your-app.vercel.app/mcp

Authentication isn't triggered by add itself -- run claude mcp list (shows ! Needs authentication), then inside a session run /mcp, select the server, and choose "Authenticate"; your browser opens for the CATAPA login, and status flips to ✔ Connected. Add --scope user instead of the default --scope local to make it available across all your projects rather than just the current one.

ChatGPT: requires a Plus/Pro/Business/Enterprise/Education account with Developer Mode enabled first (Settings -> Apps -> Advanced settings, or Settings -> Connectors -> Advanced -> Developer Mode, depending on account type -- the "Add custom connector" button only appears once this is on). Then Settings -> Connectors -> add a custom connector, paste the /mcp URL, and select OAuth as the authentication type; ChatGPT triggers the browser login on first use. (Verified via web search against OpenAI's help center rather than a direct fetch of their docs from this environment -- double-check against ChatGPT's own Settings UI if the menu names have since moved.)

How the public API tools are generated

The catapa SDK exposes a fluent resource tree (client.core.employees.list(...)) backed by an auto-generated OpenAPI client, where every operation method is fully typed -- including nested pydantic request/response models. src/catapa_mcp/public_tools.py walks that tree (catapa.resource_registry.ROOT_RESOURCES) at startup, and for every operation:

1. Copies the SDK method's own signature (minus transport-only kwargs like _headers) onto a thin async wrapper function.

2. Registers that wrapper as an MCP tool -- the MCP server derives the tool's JSON schema straight from the wrapper's type hints, so nested pydantic models become nested JSON schema automatically.

3. On invocation, validates/coerces the tool call's arguments back into the SDK's own types, calls the real SDK method, and serializes the (often pydantic) response back to JSON.

This means the tool surface tracks the SDK automatically -- upgrading catapa picks up new/changed endpoints without any code changes here.

Development

uv sync --group dev   # or: pip install -e . pytest pytest-asyncio ruff
pytest
ruff check .
ruff format .