MCP Server

MCP Server

Workestra provides a public MCP server for AI tools such as Codex, Claude Code, Claude Desktop, Cursor, VS Code, and Windsurf.

The MCP server exposes a broad tool catalog. The exact tools visible to a client are filtered by its API-key permissions, optional --features selection, and optional --read-only mode. Retrieve the live catalog for every integration session rather than relying on a cached count.

Compatibility contract

The deployed session/list responses override documentation counts when versions differ. Record the adapter version and capability counts in test logs.

What You Need

You only need:

1. A Workestra API key from your workspace.
2. An MCP client such as Codex, Claude, Cursor, VS Code, or Windsurf.
3. The public npm package: workestra-mcp.

You do not need to install or host workestra-tools. It is bundled into workestra-mcp at build time.

Create an API Key

1. Open Settings → AI → External Connections.
2. Click Create API Key.
3. Name the key, for example Codex MCP or Claude Code MCP.
4. Choose a permission preset:
   • MCP Default for normal agent access.
   • Read Only if the assistant should only view data.
5. Set an expiry date if the key is temporary.
6. Copy the key immediately. It starts with wks_ and is only shown once.

Keep this key private. Do not paste it into public chat logs, Git commits, screenshots, or support tickets.

How It Works

AI client → local workestra-mcp adapter → authenticated Workestra MCP API

The local MCP package is a thin adapter. It registers the Workestra tool names and schemas with your AI client, then forwards tool calls to Workestra's hosted API.

The workspace API key is the only secret configured in the client; the Platform URL is non-secret connection configuration. Workestra's private service credentials remain server-side.

Codex Setup: Choose STDIO

In Codex, open Connect to a custom MCP and choose STDIO.

Do not choose Streamable HTTP for Workestra. Workestra uses the local npx MCP adapter, so Codex must launch it with STDIO.

Where to Find the Values

All values are fixed except your Workestra API key:

Codex Field Reference

Fill the Codex screen exactly like this:

Prompt to Give Codex

If you want Codex to help you set it up, copy this prompt:

Connect Workestra as a custom MCP server in Codex.

Use STDIO. Do not use Streamable HTTP.

Fill the Codex fields like this:
Name: workestra
Command to launch: npx
Arguments:
  -y
  workestra-mcp
Environment variables:
  WORKESTRA_API_URL=https://platform.workestra.app
  WORKESTRA_API_KEY=wks_your_api_key_here
Environment variable passthrough: leave blank
Working directory: leave as default

After adding it, reconnect or restart the MCP server and verify that Workestra tools are available. Do not print or expose the API key.

Claude Code Setup

Run this command:

claude mcp add workestra -- npx -y workestra-mcp --api-key=wks_your_api_key_here --api-url=https://platform.workestra.app

Prompt to Give Claude Code

If you want Claude Code to install it for you, copy this prompt:

Install the Workestra MCP server for Claude Code.

Use this command:
claude mcp add workestra -- npx -y workestra-mcp --api-key=wks_your_api_key_here --api-url=https://platform.workestra.app

After installing it, verify that the Workestra MCP server is listed and that Workestra tools are available. Do not print or expose the API key.

Claude Desktop Setup

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "workestra-mcp", "--api-key=wks_your_api_key_here", "--api-url=https://platform.workestra.app"]
    }
  }
}

Cursor Setup

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "workestra-mcp"],
      "env": {
        "WORKESTRA_API_URL": "https://platform.workestra.app",
        "WORKESTRA_API_KEY": "wks_your_api_key_here"
      }
    }
  }
}

VS Code Setup

Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "workestra-mcp"],
      "env": {
        "WORKESTRA_API_URL": "https://platform.workestra.app",
        "WORKESTRA_API_KEY": "wks_your_api_key_here"
      }
    }
  }
}

Windsurf Setup

Add this to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "workestra-mcp"],
      "env": {
        "WORKESTRA_API_URL": "https://platform.workestra.app",
        "WORKESTRA_API_KEY": "wks_your_api_key_here"
      }
    }
  }
}

Other MCP Clients

Use the same pattern:

{
  "command": "npx",
  "args": ["-y", "workestra-mcp"],
  "env": {
    "WORKESTRA_API_URL": "https://platform.workestra.app",
    "WORKESTRA_API_KEY": "wks_your_api_key_here"
  }
}

The server also accepts --api-key=wks_your_api_key_here as a CLI flag.

CLI Options

npx -y workestra-mcp [options]

Environment variables:

The current public npm release verified on 2026-07-29 is workestra-mcp@2.0.4. For reproducible tests, pin it:

npx -y workestra-mcp@2.0.4 \
  --api-key=wks_your_api_key_here \
  --api-url=https://platform.workestra.app

Use unpinned workestra-mcp when you intentionally want npm's newest release.

Hosted API used by the adapter

The STDIO package validates the key and forwards calls to:

These are hosted Workestra endpoints, not a Streamable HTTP MCP transport. The client still connects to workestra-mcp over STDIO.

See Tool discovery and direct testing.

Feature Groups

The default setup exposes all feature groups allowed by your API key permissions.

Example: only expose CRM basics:

npx -y workestra-mcp --api-key=wks_your_api_key_here --features=contacts,deals,companies,activities,pipeline

Example: read-only mode:

npx -y workestra-mcp --api-key=wks_your_api_key_here --read-only

Permissions

Every tool is checked against the permissions on your Workestra API key.

For example:

Use Read Only if you want the assistant to answer questions but not change data.

--read-only is a local registration filter: write tools are not presented to the MCP client. Server-side API-key permissions are still enforced on every call and remain the security boundary.

Security Best Practices

• Use one API key per AI client.
• Prefer read-only keys for exploration and reporting.
• Give write permissions only when the workflow requires them.
• Set expiry dates for temporary access.
• Revoke keys immediately if a device or AI client is compromised.
• Do not paste API keys into public prompts, screenshots, commits, or shared documents.

Testing the Connection

After setup, restart or reconnect the MCP server in your AI client. Then try:

• "Show me my pipeline summary."
• "Search for contacts named John."
• "List open support tickets assigned to me."
• "Show overdue invoices this month."
• "Find candidates for the React developer role."

If the assistant says no Workestra tools are available, check:

1. The MCP server name is workestra.
2. The command is npx.
3. The arguments are -y and workestra-mcp.
4. The API key is set as WORKESTRA_API_KEY.
5. The API key has the permissions required by the tool you are trying to use.
6. GET /api/mcp/session returns the expected allowedToolNames.
7. The tested npm version is the version you intended to run.

For schema-level diagnostics without an MCP client, use the commands in Tool discovery and direct testing.

Still blocked?

Use API and MCP Troubleshooting. If the diagnostic sequence does not resolve the failure, email support@workestra.app with the workspace ID, UTC timestamp, client and adapter version, tool name, sanitized error, and reproduction steps. Never include the API key.

Publishing and Updates

End users do not publish anything. They run the public npm package with npx.

Workestra publishes workestra-mcp. When Workestra adds new tool names or changes tool schemas, a new package version is published. If Workestra only changes the behavior of an existing tool, users normally only need the hosted Workestra API update.