@ema.co/mcp-toolkit

MCP (Model Context Protocol) server for managing Ema AI Employees. Works with Cursor, Claude Desktop, and other MCP clients.

Installation

Option 1: npx (Recommended)

npx -y @ema.co/mcp-toolkit@latest

Option 2: Global Install

npm install -g @ema.co/mcp-toolkit
ema-mcp  # Start MCP server

Option 3: Clone & Build (Development)

git clone https://github.com/Ema-Unlimited/ema-mcp-toolkit.git
cd ema-mcp-toolkit
npm install
npm run build

Quick Start

1. Get Your Bearer Token

1. Log in to your Ema environment (e.g., app.ema.co)
2. Open browser DevTools (F12) → Network tab
3. Find any API request's Authorization: Bearer ... header
4. Copy the token (the part after "Bearer ")

2. Set Up Environment Variables

Add to your shell profile (~/.zshrc or ~/.bashrc):

# Single environment
export EMA_BEARER_TOKEN="eyJhbGciOiJSUzI1..."

# Or multiple environments (recommended)
export EMA_PROD_BEARER_TOKEN="eyJ..."    # from app.ema.co
export EMA_DEMO_BEARER_TOKEN="eyJ..."    # from demo.ema.co
export EMA_DEV_BEARER_TOKEN="eyJ..."     # from dev.ema.co
export EMA_STAGING_BEARER_TOKEN="eyJ..." # from staging.ema.co

Then reload: source ~/.zshrc

3. Configure Your AI Assistant

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "ema": {
      "command": "npx",
      "args": ["-y", "@ema.co/mcp-toolkit@latest"],
      "env": {
        "EMA_ENV_NAME": "demo",
        "EMA_PROD_BEARER_TOKEN": "${env:EMA_PROD_BEARER_TOKEN}",
        "EMA_DEMO_BEARER_TOKEN": "${env:EMA_DEMO_BEARER_TOKEN}",
        "EMA_DEV_BEARER_TOKEN": "${env:EMA_DEV_BEARER_TOKEN}",
        "EMA_STAGING_BEARER_TOKEN": "${env:EMA_STAGING_BEARER_TOKEN}"
      }
    }
  }
}

Important:

• Use @latest to always get the newest version (npx caches aggressively without it)
• The -y flag auto-confirms the npx install prompt
• Use ${env:VAR_NAME} syntax to reference shell environment variables
• After changing mcp.json, restart the MCP server: Cmd+Shift+P → "MCP: Restart Server"
• After changing ~/.zshrc, reload it AND restart Cursor for changes to take effect

Alternative: Direct tokens (if env expansion doesn't work):

{
  "mcpServers": {
    "ema": {
      "command": "npx",
      "args": ["-y", "@ema.co/mcp-toolkit@latest"],
      "env": {
        "EMA_ENV_NAME": "demo",
        "EMA_DEMO_BEARER_TOKEN": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ema": {
      "command": "npx",
      "args": ["@ema.co/mcp-toolkit"],
      "env": {
        "EMA_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

4. Verify It Works

Ask your AI assistant:

• "List ema environments" - should show your configured environments
• "List personas in demo" - should show AI Employees

Authentication

Bearer Tokens (Most Common)

Bearer tokens are JWTs obtained from the Ema web app:

1. Each token is tied to a specific environment (prod, demo, dev, staging)
2. Tokens expire after ~24 hours - get fresh ones when they expire
3. The token's issuer (iss field) must match the API endpoint:
   • ema.co token → https://api.ema.co
   • demo.ema.co token → https://api.demo.ema.co
   • etc.

API Keys (If Available)

If you have an API key (different from bearer token):

export EMA_PROD_API_KEY="your-api-key"

The toolkit will automatically exchange it for a JWT and refresh before expiry.

Verifying Token Environment

Check which environment a token belongs to:

echo $EMA_DEMO_BEARER_TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq -r .iss
# Should output: demo.ema.co

Configuration

Zero-Config Mode (Default)

No config file needed! The toolkit auto-detects environments from environment variables:

# Pattern: EMA_<ENV>_BEARER_TOKEN or EMA_<ENV>_API_KEY
export EMA_PROD_BEARER_TOKEN="..."   # → creates "prod" environment
export EMA_DEMO_BEARER_TOKEN="..."   # → creates "demo" environment
export EMA_DEV_BEARER_TOKEN="..."    # → creates "dev" environment

Default Environment:

• Set explicitly: export EMA_ENV_NAME="demo"
• Or auto-detected from available credentials

Well-known URLs (automatic):

| Environment | URL | |-------------|-----| | prod | https://api.ema.co | | <env> | https://api.<env>.ema.co |

Config File (Advanced)

For custom setups, create ema.config.yaml:

environments:
  - name: prod
    baseUrl: https://api.ema.co
    bearerTokenEnv: EMA_PROD_BEARER_TOKEN
    isMaster: true

  - name: custom
    baseUrl: https://api.custom.ema.co
    bearerTokenEnv: EMA_CUSTOM_BEARER_TOKEN

MCP Tools

| Tool | Purpose | |------|---------| | persona | Primary: AI Employee management (create/clone/modify/analyze/sanitize/optimize) | | data | v2: Simplified data management (list/upload/delete/sanitize/embedding) | | reference | v2: All reference info (envs, actions, templates, patterns, concepts, guidance) | | sync | Sync across environments | | knowledge | Data sources (legacy, use data) | | action | Agent lookup (legacy, use reference(type="actions")) | | template | Patterns (legacy, use reference) | | env | Environments (legacy, use reference(type="envs")) | | demo | Demo/RAG document utilities |

Common Workflows

Create new AI Employee:

persona(input="IT helpdesk with KB search", type="chat", name="IT Support", preview=false)

Modify existing AI Employee (LLM-Driven):

// Step 1: Get current workflow
workflow(mode="get", persona_id="abc-123")
// Returns: workflow_def, schema, guidance

// Step 2: LLM modifies the workflow_def JSON
// (add nodes, remove nodes, rewire connections)

// Step 3: Deploy modified workflow
workflow(mode="deploy", persona_id="abc-123", workflow_def={...}, preview=true)

Get reference info:

catalog(type="actions", id="send_email")      // Get action details
catalog(type="templates")                     // List templates

Dynamic Resources

| Resource | Purpose | |----------|---------| | ema://catalog/agents | Live action catalog from API | | ema://catalog/templates | Persona templates from API | | ema://catalog/patterns | Workflow patterns | | ema://docs/usage-guide | Complete usage guide (generated) | | ema://guidance/rules | Structured rules as JSON | | ema://guidance/cursor-rule | Export as Cursor .mdc rule | | ema://guidance/server-instructions | Server instructions text |

Self-Contained Guidance

The MCP is fully self-contained—no external configuration files needed.

How it works:

• Server instructions are injected on MCP init (system prompt)
• Tools include usage tips in their descriptions
• Responses include _tip and _next_step fields with contextual guidance
• env() returns a getting_started guide with workflow patterns
• persona(..., analyze=true) includes workflow_guidance with state-specific tips

For other services:

• Read ema://guidance/rules (JSON) for programmatic consumption
• Read ema://docs/usage-guide (markdown) for documentation
• Read ema://guidance/cursor-rule (.mdc) for IDE integration

All guidance flows from a single source (src/mcp/guidance.ts).

CLI

# List personas
ema personas list

# Sync a persona
ema sync persona "My Bot" --target dev --dry-run

# Check sync status
ema sync status

SDK

import { EmaClient } from "@ema.co/mcp-toolkit/sdk";

const client = new EmaClient({
  name: "prod",
  baseUrl: "https://api.ema.co",
  bearerToken: process.env.EMA_PROD_BEARER_TOKEN!,
});

// List AI Employees
const personas = await client.getPersonasForTenant();

// Get full persona with workflow
const persona = await client.getPersonaById("uuid");

// List available templates
const templates = await client.getPersonaTemplates();

// List available agents/actions
const actions = await client.listActions();

Environment Variables

| Variable | Description | |----------|-------------| | EMA_BEARER_TOKEN | Default bearer token | | EMA_<ENV>_BEARER_TOKEN | Token for specific environment (PROD, DEMO, DEV, STAGING) | | EMA_API_KEY | API key (auto-exchanges for JWT) | | EMA_<ENV>_API_KEY | API key for specific environment | | EMA_ENV_NAME | Default environment name | | EMA_AGENT_SYNC_CONFIG | Path to config file |

Troubleshooting

"Missing token for environment X"

The token isn't set or isn't being passed to the MCP server:

1. Check the token is set in your shell: echo $EMA_X_BEARER_TOKEN
2. Ensure it's in ~/.zshrc and you've run source ~/.zshrc
3. Restart the MCP server in Cursor after config changes
4. If ${env:...} isn't working, paste the token directly in mcp.json

"Invalid API key" error

You're using a bearer token (JWT) with an _API_KEY variable name:

• Rename EMA_X_API_KEY to EMA_X_BEARER_TOKEN

Only some environments detected

Check each token's issuer matches its environment:

# Should show: demo.ema.co
echo $EMA_DEMO_BEARER_TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq -r .iss

Token expired / 401 errors

Bearer tokens expire after ~24 hours. Get fresh tokens from each environment's web app.

MCP server not picking up new tokens

1. Run source ~/.zshrc to reload env vars
2. Restart MCP server: Cmd+Shift+P → "MCP: Restart Server" → "ema"
3. Or restart Cursor entirely

Cursor ${env:...} not expanding

Some Cursor versions have issues with env var expansion. Workaround: paste tokens directly in mcp.json (less secure but works).

License

MIT - see LICENSE