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 350 tools across 35 feature groups. These tools let an AI assistant search and update workspace data across CRM, finance, support, projects, time, planning, recruiting, stock, procurement, field service, marketing, automations, and more.

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 -> Administration -> API.
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 sk_live_ 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

Your computer                         Workestra cloud

Codex / Claude / Cursor
        |
        | stdio
        v
workestra-mcp
local adapter installed by npx
        |
        | HTTPS + Workestra API key
        v
workestra.app/api/mcp/*
Vercel server routes
        |
        | server-side Supabase access
        v
Workspace database

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.

Your Supabase service role key is never installed on the user's computer. It stays on the Workestra 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://www.workestra.app
  WORKESTRA_API_KEY=sk_live_your-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=sk_live_your-key-here --api-url=https://www.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=sk_live_your-key-here --api-url=https://www.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=sk_live_your-key-here", "--api-url=https://www.workestra.app"]
    }
  }
}

Cursor Setup

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

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "workestra-mcp"],
      "env": {
        "WORKESTRA_API_URL": "https://www.workestra.app",
        "WORKESTRA_API_KEY": "sk_live_your-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://www.workestra.app",
        "WORKESTRA_API_KEY": "sk_live_your-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://www.workestra.app",
        "WORKESTRA_API_KEY": "sk_live_your-key-here"
      }
    }
  }
}

Other MCP Clients

Use the same pattern:

{
  "command": "npx",
  "args": ["-y", "workestra-mcp"],
  "env": {
    "WORKESTRA_API_URL": "https://www.workestra.app",
    "WORKESTRA_API_KEY": "sk_live_your-key-here"
  }
}

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

CLI Options

npx -y workestra-mcp [options]

Environment variables:

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=sk_live_your-key-here --features=contacts,deals,companies,activities,pipeline

Example: read-only mode:

npx -y workestra-mcp --api-key=sk_live_your-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.

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.

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.