MCP Server (Model Context Protocol)

The Workestra MCP server provides 63 tools across 13 feature groups that AI agents can use to interact with your workspace data — CRM, invoicing, tickets, projects, analytics, recruiting, knowledge base, quotations, and more — all secured by your Workestra API key.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI tools like Claude, Cursor, and VS Code Copilot discover and call functions on external systems. Once connected, your AI assistant can directly search contacts, create deals, manage tickets, track projects, analyze revenue, and more — without copy-pasting data or building custom integrations.

Authentication

The MCP server uses your Workestra API key for authentication. Your API key is the only credential you need — it automatically determines which workspace you access and what operations are allowed.

Creating an API Key

1. Go to Settings → Administration → API in the Workestra dashboard
2. Click Create API Key
3. Name your key (e.g., "Claude Code MCP")
4. Select the permissions you need:
   • Read permissions for search and viewing data
   • Create permissions for adding new records
   • Update permissions for modifying existing records
   • Delete permissions for removing records
5. Copy your key — it starts with sk_live_ and is only shown once

How It Works

Your machine                        Workestra
┌─────────────────────┐            ┌──────────────────┐
│ Claude / Cursor      │            │                  │
│   ↕ stdio            │            │  api_keys table  │
│ workestra-mcp server │──verify──▶│  (SHA-256 hash)  │
│   (runs locally)     │            │       ↓          │
│                      │──query───▶│  workspace data  │
└─────────────────────┘            └──────────────────┘

1. You provide your API key (sk_live_...)
2. The server hashes it and verifies it against the api_keys table
3. Your workspace ID is resolved from the key — all queries are scoped automatically
4. Permissions on the key control which tools are allowed
5. A user can only access the workspace their API key belongs to

Security Best Practices

• Use separate API keys for each AI tool or agent
• Grant only the permissions your workflow requires
• Enable read-only mode when you only need to query data
• Set expiration dates for temporary access
• Revoke keys immediately if compromised

Connect to the MCP Server

Cursor

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

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "@workestra/mcp"],
      "env": {
        "WORKESTRA_API_KEY": "sk_live_your-key-here"
      }
    }
  }
}

VS Code

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

{
  "servers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "@workestra/mcp"],
      "env": {
        "WORKESTRA_API_KEY": "sk_live_your-key-here"
      }
    }
  }
}

Claude Code

claude mcp add workestra -- npx -y @workestra/mcp --api-key=sk_live_your-key-here

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "@workestra/mcp", "--api-key=sk_live_your-key-here"]
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "workestra": {
      "command": "npx",
      "args": ["-y", "@workestra/mcp"],
      "env": {
        "WORKESTRA_API_KEY": "sk_live_your-key-here"
      }
    }
  }
}

ChatGPT / Other Clients

MCP is an open protocol supported by many clients. The server accepts the WORKESTRA_API_KEY environment variable or the --api-key CLI flag.

CLI Options

npx -y @workestra/mcp [options]

Feature Groups

Control which tools are available:

Example — enable only contacts and deals:

npx -y @workestra/mcp --api-key=sk_live_... --features=contacts,deals

Example — enable CRM and support tools:

npx -y @workestra/mcp --api-key=sk_live_... --features=contacts,deals,companies,activities,pipeline,tickets

Tools

Contacts

Deals

Companies

Activities

Pipeline & Dashboard

Invoicing

Tickets

Projects

Analytics

Recruiting

Knowledge Base

Quotations

Workspace

Permissions

Each tool requires specific permissions on your API key:

Building Autonomous Agents

Pass a Workestra API key with restricted permissions when spawning the MCP server:

npx -y @workestra/mcp --api-key=sk_live_your-key --read-only --features=contacts,deals

Read-Only Mode

Use --read-only to prevent any write operations:

npx -y @workestra/mcp --api-key=sk_live_your-key --read-only

Managing API Keys

API keys are managed at Settings → Administration → API in the Workestra dashboard.

Each API key has:

• Granular permissions — control read/create/update/delete per entity type
• Workspace scoping — automatically limits all queries to your workspace
• Expiration dates — optional, for time-limited access
• Usage tracking — last used timestamp and audit logs
• Instant revocation — delete a key to revoke access immediately

Example Prompts

Once connected, try these prompts in your AI assistant:

• "Show me all leads that were created this month"
• "Create a new contact for John Smith at Acme Corp"
• "What's the total value of our open deals?"
• "Move the Acme deal to the proposal stage"
• "Show me my pipeline summary"
• "List all activities for this week"
• "Create a follow-up call for tomorrow with Sarah"
• "What are my overdue invoices?"
• "Show me all open support tickets assigned to me"
• "Create a task in the Q2 Launch project"
• "What's our revenue trend this quarter?"
• "List candidates in the interview stage for the Senior Engineer role"
• "Search the knowledge base for onboarding guides"
• "Show me the sales forecast for this month"