callman-mcp

MCP server for Callman — lets Claude Code, Claude Desktop, Cursor, OpenAI Codex and Gemini CLI work inside your Callman account: build and organise collections, import the endpoints found in your code, run requests, create and run test scenarios, author and run UI tests (web, Android, iOS), and draw system-design diagrams. Works with Callman cloud and on-prem.

AI tool ──stdio──▶ callman-mcp (this package, on your machine) ──HTTPS──▶ your Callman server

Everything the AI tool does goes through the same REST API the desktop app uses, as you, limited to the permissions of the token you created and your role in each workspace.

Quick start

1. Create a token — Callman desktop app → profile menu → AI tools → New token. Pick a preset (Read only, Build collections, Full, no delete, Full) or choose permissions one by one. The token is shown once, together with a ready-to-paste config for your tool.

2. Add the server to your AI tool (needs Node.js 20+):

   Claude Code

   claude mcp add callman --scope user -e CALLMAN_API_URL=https://api.callman.io -e CALLMAN_TOKEN=<PASTE_YOUR_TOKEN> -- npx -y callman-mcp

   Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Gemini CLI (~/.gemini/settings.json)

   {
     "mcpServers": {
       "callman": {
         "command": "npx",
         "args": ["-y", "callman-mcp"],
         "env": {
           "CALLMAN_API_URL": "https://api.callman.io",
           "CALLMAN_TOKEN": "<PASTE_YOUR_TOKEN>"
         }
       }
     }
   }

   OpenAI Codex (~/.codex/config.toml)

   [mcp_servers.callman]
   command = "npx"
   args = ["-y", "callman-mcp"]
   
   [mcp_servers.callman.env]
   CALLMAN_API_URL = "https://api.callman.io"
   CALLMAN_TOKEN = "<PASTE_YOUR_TOKEN>"

3. Check it — CALLMAN_API_URL=… CALLMAN_TOKEN=… npx -y callman-mcp doctor prints the server, your user, token scopes, workspaces and which tools the token can use. Then ask your AI tool: "list my Callman workspaces".

Things to try: "add the endpoints in src/routes/users.ts to a new collection Users API", "run GET /users with the Staging environment", "create a scenario that logs in, creates an order and checks it appears", "write a UI test that signs in to the Android app and opens the cart, then run it on my emulator", "draw the architecture of this repo and share it with the Team workspace".

Run a local build (before it is published, or while developing it)

git clone … callman-mcp && cd callman-mcp
npm install --legacy-peer-deps && npm run build      # → dist/index.js

Point the AI tool at the file instead of npx -y callman-mcp:

claude mcp add callman --scope user -e CALLMAN_API_URL=http://localhost:8080 -e CALLMAN_TOKEN=<PASTE_YOUR_TOKEN> -- node /abs/path/to/callman-mcp/dist/index.js

(JSON configs: "command": "node", "args": ["/abs/path/to/callman-mcp/dist/index.js"].) Rebuild after changing the source; AI tools start a fresh process per session.

Configuration

| Variable | Default | Meaning | |---|---|---| | CALLMAN_API_URL | https://api.callman.io | Server origin. On-prem: the address the desktop app uses (any path prefix is kept; a trailing /api is accepted). | | CALLMAN_TOKEN | — | Personal token (cm_pat_…). Without it the server still starts; whoami explains how to set one. | | CALLMAN_TOKEN_FILE | — | Read the token from a file instead (Docker/Kubernetes secrets). | | CALLMAN_WORKSPACE_ID | — | Optional default workspace: where NEW things go when a tool is not told, and which workspace wins a name that exists in several. It never limits what the tool sees — every workspace stays reachable. Change it at runtime with use_workspace. | | CALLMAN_ALLOW_RUN | 1 | 0 removes run_request / run_collection (no local execution). | | CALLMAN_LOG_LEVEL | warn | silent, error, warn, info, debug — to stderr (stdout is the protocol). | | CALLMAN_TIMEOUT_MS | 30000 | Per API call. | | CALLMAN_RUN_TIMEOUT_MS | 600000 | Budget for one local run. | | CALLMAN_MAX_BODY_BYTES | 16384 | Response-body preview cap in run output (max 262144). |

Workspaces

One token, every workspace. The token acts as you in all workspaces you belong to, so a single MCP entry covers them all — no per-workspace setup:

• Lists and searches (list_collections, search_requests, list_environments, list_connections, list_scenarios) cover every workspace; each row says where it lives. Pass workspace to narrow to one.
• Names are found wherever they are. The default workspace is searched first, then all the others; a name that exists in several comes back as candidates tagged with their workspace.
• Creating goes to the workspace you name, the workspace of the collection you create into, or the default. use_workspace sets the default for the session ("work in Payments now").

Tools (87) and the permission each needs

| Area | Tools | Scope | |---|---|---| | Meta | whoami | — | | Workspaces | list_workspaces, use_workspace, list_workspace_members | workspaces:read (always on) | | | add_workspace_member, update_workspace_member, remove_workspace_member | members:manage (+ owner role) | | Collections | list_collections, get_collection_tree, export_collection | collections:read | | | create_collection, update_collection, create_folder, update_folder | collections:write | | | delete_collection, delete_folder | collections:delete | | Requests | search_requests, get_request | requests:read | | | create_request, update_request, move_requests | requests:write | | | create_requests_bulk | requests:write (existing collection) / import:write (new collection, atomic) | | | delete_requests | requests:delete | | | run_request, run_collection | requests:run | | Contract checks | get_contract_checks, test_contract_rules | requests:read | | | add_contract_rules, update_contract_rule, set_data_contract | requests:write | | | delete_contract_rules, delete_data_contract | requests:delete | | Connections | list_connections (safe record, never credentials) | requests:read or scenarios:read | | Import | import_content (Postman, OpenAPI, Insomnia, Bruno, Callman export, cURL, .http) | import:write (requests:write for cURL/.http into an existing collection) | | | import_scenario | import:write | | Environments | list_environments, get_environment | environments:read (+ environments:reveal for values) | | | create_environment, update_environment, set_environment_variables, set_global_variables | environments:write (unset also needs environments:delete) | | | delete_environment | environments:delete | | Scenarios | list_scenarios, get_scenario, get_scenario_report | scenarios:read | | | create_scenario, update_scenario, patch_scenario, submit_scenario | scenarios:write | | | run_scenario | scenarios:run | | | delete_scenario | scenarios:delete | | UI tests | list_ui_tests, get_ui_test, validate_ui_test, list_ui_test_folders, list_ui_test_devices, get_ui_test_run (screenshots as images), list_ui_test_runs, list_ui_test_schedules, list_ui_test_versions, export_ui_tests | ui_tests:read | | | create_ui_test, update_ui_test, patch_ui_test_steps, create_ui_test_folder, update_ui_test_folder, move_ui_tests, create_ui_test_schedule, update_ui_test_schedule, submit_ui_test, review_ui_test, restore_ui_test_version, import_ui_tests | ui_tests:write | | | run_ui_test, run_ui_tests, cancel_ui_test_run, run_ui_test_schedule_now | ui_tests:run | | | delete_ui_test, delete_ui_test_folder, delete_ui_test_schedule | ui_tests:delete | | Diagrams | list_diagrams, get_diagram (graph, mermaid, source, full) | diagrams:read | | | create_diagram, update_diagram (nodes, Mermaid or BPMN 2.0 source, kind: "bpmn"), patch_diagram (ops) | diagrams:write | | | share_diagram | diagrams:share | | | delete_diagram | diagrams:delete |

UI tests need a backend with the ui_tests:* token permissions (older servers answer PAT_ROUTE_FORBIDDEN). Web flows run on the server's UI-test runner when the installation has one; Android and iOS flows — and web flows without a server runner — run on your own Callman desktop app: open it, sign in and turn on Settings → AI tools → "Let AI tools run UI tests on this computer", then connect a device or start an emulator/simulator. list_ui_test_devices shows what is available.

Contract checks and connections need a backend that maps /api/contract-rules, /api/data-contracts and /api/connections for personal tokens (callman-backend with the MCP scope rows); an older backend answers those tools with PAT_ROUTE_FORBIDDEN.

Conventions: arguments are strict — a misspelled or unknown key is an error that lists the valid ones, never silently ignored; names work wherever an id does (ambiguous names return candidates; deletions need the exact name or the id); big writes take dryRun: true; deletions require confirm: true; every write reports what it resolved (resolved: [{ input, matched, id }]); reads come back in the same shape the writes take; outputs are size-bounded and say when they truncate.

Resources — callman://docs/overview, …/docs/request-schema, …/docs/contracts, …/docs/scenario-nodes, …/docs/scripting/{pm-api,db-queries,templating,sandbox}, …/docs/ui-tests, …/docs/ui-test-steps (every UI-test step, generated from callman-core), …/docs/diagram-schema, callman://diagram/components[/{category}] (the component catalog, generated from callman-core), and live data: callman://workspaces, callman://workspace/{workspace}/collections, …/environments, callman://collection/{collection}/tree, callman://request/{request}, callman://environment/{environment}, callman://scenario/{scenario}, callman://ui-test/{flow}, callman://diagram/{diagram}.

Prompts — import_endpoints_from_code, design_system_diagram, create_scenario_from_flow, document_collection.

Security model

• Your identity, narrowed. A personal token acts as you in every workspace you belong to, with your role there (a viewer's token cannot write), limited to its scopes. The server enforces scopes on every route; areas outside the AI-tool surface (mocks, request history, API-scenario schedules, connection editing, admin) are refused. Connections are readable only as their safe record (id, name, type — never credentials).
• UI tests on your machine only when you say so. A desktop run happens only while your own desktop app is signed in with "Let AI tools run UI tests on this computer" switched on (off by default); the app shows a banner with Stop while an AI-started run is going. UI-test dataset values with secret-looking keys are masked like environment values and can never be written back masked; run reports mask Authorization/Cookie headers.
• Secrets stay masked. Environment, global and scenario variable values come back as ••••ab unless the token holds environments:reveal and the call passes reveal: true. Masked values can never be written back (a masked request or scenario secret sent back unchanged keeps the stored value). Request auth secrets, sensitive headers and scenario node secrets are masked by this server on the way to the model.
• Local runs keep values local. run_request / run_collection fetch the collection bundle, resolve variables and send requests on your machine (the same engine as the desktop app and callme-cli). The model receives status, timing, the request as sent, bounded bodies, test and contract results and the names of variables scripts changed — every variable value is shown as its {{key}}, never the value.
• Deletes are opt-in twice: a *:delete scope on the token and confirm: true on the call.
• Tokens always expire, are rate-limited per token, attributed in the audit trail, revocable at any time in the desktop app, and the whole feature is behind the mcp feature flag an administrator controls.

On-prem

Use the address the desktop app uses (http(s)://<host>[:port][/prefix]). The /api path must be reachable from the machine running the AI tool. Corporate TLS: add NODE_EXTRA_CA_CERTS=/path/to/ca.pem to the server's env. Air-gapped: npm pack callman-mcp on a connected machine, npm i -g ./callman-mcp-<version>.tgz on the target, and use callman-mcp as the command instead of npx -y callman-mcp. The administrator enables AI tools in the admin panel (feature flag AI tools (MCP)).

Troubleshooting

| Symptom | Fix | |---|---| | 401 | Token missing, expired or revoked — create a new one and update the config. | | 403 PAT_SCOPE_MISSING | The message names the scope; create a token that has it. | | 403 PAT_ROUTE_FORBIDDEN | That area is not available to AI tools. | | 403 FEATURE_DISABLED | An administrator switched AI tools off. | | UI_TEST_DESKTOP_OFFLINE | Open the Callman desktop app, sign in, turn on Settings → AI tools → "Let AI tools run UI tests on this computer". | | UI_RUNNER_UNAVAILABLE | No server UI-test runner — run with target: "desktop"; schedules need the runner. | | 403 on a write | You are a viewer in that workspace. | | "pass workspace" | Creating something with several workspaces and no default — name one, or use_workspace for the session. Reading never needs it. | | REF_AMBIGUOUS with workspaces | The same name exists in several workspaces — pass workspace or use the id. | | Tool not listed in the client | Node 20+? Can npx reach the registry? Run callman-mcp doctor. | | Changes not visible in the app | Switch back to the app (it refreshes on focus) or press Refresh in the diagram library. |

Embedding

import { createCallmanMcpServer, resolveConfig } from "callman-mcp";

const { server } = createCallmanMcpServer({
  config: resolveConfig({ env: { CALLMAN_API_URL: "…", CALLMAN_TOKEN: "…", CALLMAN_ALLOW_RUN: "0" } }),
  fetch, // injectable
});
await server.connect(transport); // any MCP transport

ESM and CommonJS builds are shipped. The tool layer never reads the environment, the file system or stdout — only the bin (dist/index.js) does.

Development

nvm use                                   # Node 22
npm install --legacy-peer-deps            # npm 10's arborist trips over a dev-only peer set
npm run lint && npm run build && npm test && npm run smoke

tests/fixtures/fake-backend.ts is an in-memory Callman backend (envelope, scopes, masking, pagination, CAS, runs); contract tests drive every tool through a real MCP client. npm run smoke starts the built server over stdio. Shared logic (cURL/.http parsers, the diagram document contract and component catalog, the request runner) comes from callman-core.

MIT

callman-mcp