MCP Server

Model Context Protocol server that exposes the Wocha Management API to AI assistants.

@wocha/mcp is a Model Context Protocol (MCP) server that wraps the Wocha Management API. Connect it to Claude Desktop, Cursor, or any MCP-compatible client so AI agents can inspect and manage users, organisations, OAuth applications, webhooks, connections, feature flags, and more.

Installation

Install globally:

pnpm add -g @wocha/mcp

Or scaffold with the CLI

npx @wocha/cli init --framework nextjs

Or run with npx:

npx @wocha/mcp

The server communicates over stdio — your MCP client spawns the process and passes credentials via environment variables.

Configuration

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 (self-hosted or local)

Example:

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

Tools

The server exposes Management API operations as MCP tools. Read-only tools are safe for inspection; mutating tools change tenant configuration — confirm with the user before calling them.

Users and organisations

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_update`	Update display name or metadata
`organisations_list_members`	List org members
`organisations_add_member`	Add user to org with role
`organisations_remove_member`	Remove member from org

Permissions

Tool	Description
`permissions_check`	Check if a subject has a permission on a resource
`permissions_lookup`	Lookup resources a subject can access
`permissions_expand`	Expand a permission tree for a resource

Applications and webhooks

Tool	Description
`applications_list`	List OAuth applications
`applications_create`	Register a new OAuth application
`webhooks_list`	List webhook subscriptions
`webhooks_create`	Create webhook subscription
`webhooks_update`	Update webhook URL, events, or status
`webhooks_delete`	Delete webhook subscription
`webhooks_deliveries`	List delivery history for a webhook
`webhook_verify`	Verify an `X-Wocha-Signature` header against a payload

Connections, events, and flags

Tool	Description
`connections_list`	List social, enterprise SSO, and SCIM connections
`events_list`	List recent platform events
`feature_flags_list`	List feature flags
`feature_flags_evaluate`	Evaluate flags for a user or org
`feature_flags_create`	Create a feature flag
`feature_flags_update`	Update a feature flag

Environments and tenant

Tool	Description
`environments_list`	List deployment environments
`environments_create`	Create a deployment environment
`api_keys_list`	List management API keys
`tenant_status`	Tenant health, subscription, and usage summary

Resources

Read-only resources provide quick context without tool calls:

URI	Description
`wocha://tenant/config`	Tenant configuration summary
`wocha://tenant/events/recent`	Last 20 platform events
`wocha://tenant/connections`	Active auth connections
`wocha://tenant/environments`	Deployment environments
`wocha://tenant/feature-flags`	Feature flags defined for the tenant

Usage with AI assistants

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"
      }
    }
  }
}

Restart Cursor after saving. The Wocha tools appear in the MCP panel and are available to Agent mode.

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"
      }
    }
  }
}

On Windows, the config file is at %APPDATA%\Claude\claude_desktop_config.json.

Other MCP clients

Any client that supports stdio MCP servers can run:

WOCHA_API_KEY=wocha_mgmt_... WOCHA_TENANT=acme npx @wocha/mcp

Example prompts

Once connected, you can ask your assistant:

"List the last 10 users in my Wocha tenant"
"Create a webhook subscription for user.created events pointing to my staging URL"
"Check if user usr_abc has edit permission on document doc_123"
"Show me the tenant health and subscription status"
"Evaluate feature flags for organisation org_xyz"

The server returns JSON responses from the Management API. Mutating operations include hints in the server instructions to confirm with the user first.

Security

Use a Management API key with the minimum scopes needed for your workflow
Never commit API keys to source control — use environment variables in MCP config
Prefer read-only inspection in shared or production tenants; use a dedicated dev tenant for mutating operations
Rotate keys if they are exposed

Learn more

TypeScript SDK — direct Management API client
CLI reference — terminal workflows for the same operations
API reference

MCP Server

On this page