@wocha/mcp

Model Context Protocol (MCP) server that wraps the Wocha Management API and exposes it as MCP tools and resources for AI agents.

Use it with Claude Desktop, Cursor, or any MCP-compatible client to inspect and manage users, organisations, OAuth applications, webhooks, connections, feature flags, and more — directly from your AI assistant.

Installation

npm install -g @wocha/mcp

Or run without installing globally:

npx @wocha/mcp

Configuration

The server reads credentials from environment variables:

| Variable | Required | Description | |----------|----------|-------------| | WOCHA_API_KEY | Yes | Management API key (wocha_mgmt_...) or OAuth access token | | WOCHA_TENANT | One of tenant/url | Tenant slug (resolves to https://{tenant}.api.wocha.ai/v1) | | WOCHA_API_URL | One of tenant/url | Platform API base URL (e.g. https://acme.api.wocha.ai or http://localhost:3400) |

Example:

export WOCHA_API_KEY="wocha_mgmt_..."
export WOCHA_TENANT="acme"
# or: export WOCHA_API_URL="https://acme.api.wocha.ai"

Tools

| Tool | Description | |------|-------------| | users_list | List users with pagination | | users_get | Get user by ID | | users_create | Create a new user | | organisations_list | List organisations | | organisations_get | Get organisation by ID | | organisations_create | Create organisation | | organisations_list_members | List org members | | applications_list | List OAuth applications | | applications_create | Create OAuth application | | webhooks_list | List webhook subscriptions | | webhooks_create | Create webhook | | connections_list | List auth connections (social, enterprise, SCIM) | | events_list | List recent platform events | | feature_flags_list | List feature flags | | feature_flags_evaluate | Evaluate flags for a user/org | | api_keys_list | List management API keys | | tenant_status | Tenant health, subscription, and usage summary |

Resources

| URI | Description | |-----|-------------| | wocha://tenant/config | Tenant configuration summary | | wocha://tenant/events/recent | Last 20 platform events | | wocha://tenant/connections | Active auth connections |

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "wocha": {
      "command": "npx",
      "args": ["-y", "@wocha/mcp"],
      "env": {
        "WOCHA_API_KEY": "wocha_mgmt_...",
        "WOCHA_TENANT": "your-tenant"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or global Cursor MCP settings:

{
  "mcpServers": {
    "wocha": {
      "command": "npx",
      "args": ["-y", "@wocha/mcp"],
      "env": {
        "WOCHA_API_KEY": "wocha_mgmt_...",
        "WOCHA_TENANT": "your-tenant"
      }
    }
  }
}

For self-hosted deployments, use WOCHA_API_URL instead of WOCHA_TENANT:

{
  "mcpServers": {
    "wocha": {
      "command": "npx",
      "args": ["-y", "@wocha/mcp"],
      "env": {
        "WOCHA_API_KEY": "wocha_mgmt_...",
        "WOCHA_API_URL": "http://localhost:3400"
      }
    }
  }
}

Other MCP clients

Any client that supports stdio MCP servers can run:

WOCHA_API_KEY=wocha_mgmt_... WOCHA_TENANT=acme wocha-mcp

Development

From the monorepo root:

pnpm --filter @wocha/mcp build
pnpm --filter @wocha/mcp dev

License

Apache-2.0