@ema.co/mcp-toolkit

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

Once set up, you can talk to your AI assistant in plain English:

• "List all my AI Employees"
• "Create a new chat bot called IT Support"
• "Show me the workflow for the Sales Assistant"
• "What went wrong in the last conversation with the HR Bot?"

The toolkit connects tools like Cursor, Claude Desktop, Claude Code, Windsurf, and VS Code Copilot directly to your Ema account.

No coding experience required. Estimated setup time: 5 minutes.

Prerequisites

Before you begin, make sure you have:

• [ ] Node.js 18+ installed (download here — choose LTS)
• [ ] An Ema account with access to at least one environment (demo, dev, staging, or prod)
• [ ] One of the supported AI tools installed (Cursor, Claude Desktop, Claude Code, VS Code, Windsurf)
• [ ] gcloud CLI (optional) — required for knowledge search. Install: cloud.google.com/sdk/docs/install, then run gcloud auth login with your @ema.co account

To check if Node.js is installed, open your terminal and run:

node --version
# Should show v18.x.x or higher

Quick Start

Step 1: Configure Your AI Tool

Pick your platform and add the MCP server config. No environment variables needed -- authentication happens automatically in the next step.

Cursor

1a. Open MCP settings:

1. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows)
2. Type "MCP" -> select "MCP: Open User Configuration"
   • This opens ~/.cursor/mcp.json

1b. Paste this configuration:

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

1c. Restart the MCP server:

1. Press Cmd+Shift+P -> "MCP: Restart Server" -> select "ema"
2. A green dot next to "ema" in the MCP panel means it's running

Claude Desktop

Config file location:

| OS | Path | | ------- | ----------------------------------------------------------------- | | Mac | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Quick way to open on Mac:

mkdir -p ~/Library/Application\ Support/Claude
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Paste this configuration:

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

Fully quit Claude Desktop (Cmd+Q) and reopen it. Look for the hammer icon (tools) at the bottom of the chat input.

Claude Code (CLI)

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

That's it. Authentication happens via browser login (see Step 2).

Tip: Add --global to make it available across all projects: claude mcp add --global ema -- npx -y @ema.co/mcp-toolkit@latest

VS Code (GitHub Copilot)

Requires a GitHub Copilot subscription with MCP support enabled.

1. Open Settings (Cmd+,) -> search "mcp" -> enable "Chat > Agent > MCP: Enabled"
2. Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "ema": {
      "command": "npx",
      "args": ["-y", "@ema.co/mcp-toolkit@latest"]
    }
  }
}

Note: VS Code uses "servers" (not "mcpServers" like Cursor).

3. Cmd+Shift+P -> "MCP: List Servers" -> verify "ema" is listed and running
4. Open Copilot Chat -> switch to Agent mode

Windsurf

1. Press Cmd+Shift+P -> "Open MCP Configuration"
2. Add to ~/.codeium/windsurf/mcp_config.json:

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

3. Restart Windsurf, open Cascade (AI chat)

Step 2: Log In

In your AI tool's chat, type:

Login to Ema

The assistant calls config(method="login") and a browser window opens. Log in with your organization's SSO (Okta, Google, etc.) -- the token is captured automatically and stored as a profile. No manual token copying needed.

First time? If Playwright is not installed, the toolkit opens your system browser and guides you through a one-time paste-token fallback. For fully automatic login, install Playwright: npm install -g playwright && npx playwright install chromium

To log in to a specific environment (e.g., staging):

Login to Ema staging

Step 3: Verify It Works

Ask your AI assistant:

List all my AI Employees

You should see your personas listed. Then try:

Show me the workflow for <persona name>

Using the Toolkit

Everything works through natural language. Describe what you want and the assistant handles the details using the MCP tools behind the scenes.

Explore Your Environment

Start by seeing what's available:

List all my AI Employees

Show me the templates available for creating new personas

What's my current profile?

The assistant calls persona(method="list"), template(method="list"), and config() under the hood. You don't need to know the tool names -- just ask.

Create an AI Employee

Describe what you need in plain English:

I need a voice AI employee that:
- Answers IT support questions
- Can look up information in our knowledge base
- Escalates to a human if it can't help

The assistant will:

1. Search for the right template
2. Ask you clarifying questions (knowledge sources, escalation rules, hours)
3. Create the persona with the right workflow
4. Preview the configuration before deploying
5. Deploy only after you confirm

You can also create simpler personas directly:

Create a new chat persona called "Customer FAQ Bot" that answers
questions from a knowledge base

Upload Knowledge

Give your AI Employees data to work with:

Upload the file /path/to/faq.pdf to the IT Support persona's knowledge base

Then verify it was indexed:

How many documents does the IT Support bot have in its knowledge base?

The toolkit supports PDF, DOCX, TXT, CSV, and other common formats. You can upload individual files or entire directories.

Inspect and Modify Workflows

Every AI Employee has a workflow that defines how it processes requests. The modification pattern is always three steps: get, modify, deploy.

View a workflow:

Show me the workflow for the Sales Assistant

Add a step:

Add an approval step before the Sales Bot sends any emails

The assistant will:

1. Get the current workflow (workflow(mode="get"))
2. Show you what it plans to change
3. Preview the change without deploying
4. Deploy only after you confirm

More examples:

Remove the web search step from the HR Bot's workflow

Change the IT Support bot to escalate when confidence is below 70%

Debug Issues

When something goes wrong with an AI Employee, trace the problem step by step:

Start with recent conversations:

Show me recent conversations for the HR Assistant

Drill into a specific run:

Debug the last workflow run for the Sales Bot — what went wrong?

Get detailed traces:

Show me the action-level details for workflow run abc-123

The debug flow follows a natural path: conversations -> pick a workflow run -> show work (all actions) -> action detail (inputs, outputs, LLM calls).

Search Platform Knowledge

The knowledge tool searches across actions, patterns, rules, and platform concepts:

Search for email-related actions in Ema

What workflow patterns are available for voice bots?

How do I wire search results to an LLM?

Generate Documents

For document-type AI Employees, generate content end-to-end:

Generate a proposal about Q3 marketing strategy using the Content Writer persona

The assistant handles the full pipeline: create project, generate outline, generate sections, and poll until complete. You can refine sections afterward:

Make the executive summary more concise

Knowledge Search (requires gcloud)

The knowledge tool searches Ema's Discovery Engine for actions, patterns, rules, and platform concepts. It requires Google Cloud authentication:

# One-time setup
gcloud auth login  # Use your @ema.co Google account

Then in your AI tool:

Search for email-related actions in Ema

How do I wire search results to an LLM?

If gcloud is not installed or authenticated, knowledge search falls back to a keyword-only mode with limited results. For the best experience, install gcloud and authenticate.

Tip: On Mac, install via brew install google-cloud-sdk. On other platforms, see cloud.google.com/sdk/docs/install.

Tips

• Ask in plain English -- the assistant understands intent, not just commands
• The assistant previews before deploying -- you always get to review changes
• Use knowledge() to learn -- search for actions, patterns, and best practices when you're unsure how something works
• Switch profiles -- ask "switch to my staging profile" or use config(method="use", profile="acme-corp-staging")
• Multiple tenants -- if you have access to multiple Ema tenants, config(method="login") lets you pick which one

Reference

MCP Tools

| Tool | Purpose | | -------------- | --------------------------------------------------------------------------- | | persona | AI Employee management (list/get/create/update/delete, data, sync, version) | | workflow | Workflow get/deploy/validate/optimize (LLM-driven modification) | | knowledge | Platform search, publish, and source management (requires gcloud auth) | | debug | Audit conversations and workflow execution traces | | conversation | Chat conversation management and HITL continuations | | document | Document generation from document-type AI Employees | | template | Persona template CRUD (create/list/get/update/delete) | | config | Profile management, auth, environment switching | | feedback | Agent feedback collection (quality, corrections, probes) |

Internal aliases (backwards compat): action, catalog, reference, data, sync, demo

Tool Call Examples

Create a new AI Employee:

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

Workflow modification (3-step pattern):

workflow(mode="get", persona_id="abc-123")
// LLM modifies the workflow_def JSON
workflow(mode="deploy", persona_id="abc-123", base_fingerprint="<fingerprint>", workflow_def={...})

Search platform knowledge:

knowledge("how to wire search results to LLM")
knowledge("send_email")

Authentication

Authentication is handled automatically via browser-based OAuth. On first use, the agent opens a browser window for you to log in via your organization's SSO (Okta, Google, etc.). The token is captured and stored locally.

Your credentials are stored in ~/.ema-mcp/credentials.json as profiles. Each profile represents a tenant + environment combination (e.g., "acme-corp-prod"). Use config(method="profiles") to list them.

Key commands:

| Command | What it does | | ---------------------------------------------- | ------------------------------ | | config() | Show current profile and auth status | | config(method="login") | Login via browser (default: prod) | | config(method="login", env="demo") | Login to a specific environment | | config(method="profiles") | List all profiles | | config(method="use", profile="acme-staging") | Switch active profile | | config(method="logout") | Remove current profile credential |

Tokens expire after ~24 hours. When your token expires, the toolkit will prompt you to re-authenticate. Just say "login to Ema" again.

Profiles

A profile = tenant + environment + auth credentials. Example: acme-corp-prod = Acme Corp on production.

• Profiles are created automatically when you log in
• The active profile determines which tenant and environment all tools target
• Switch profiles to work across multiple tenants or environments
• Profile data is stored in ~/.ema-mcp/config.json

Ema Environments

| Environment | App URL | API URL | | ----------- | -------------------------------------------- | ------------------------------------------------ | | Production | app.ema.co | api.ema.co | | Demo | demo.ema.co | api.demo.ema.co | | Staging | staging.ema.co | api.staging.ema.co | | Dev | dev.ema.co | api.dev.ema.co |

Configuration

The primary configuration method is profile-based. When you run config(method="login"), the toolkit stores your credentials and tenant information in ~/.ema-mcp/config.json. All tools automatically use the active profile.

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

Dynamic Resources

| Resource | Purpose | | ------------------------------------------ | ------------------------------------------ | | ema://docs/usage-guide | Complete usage guide (auto-generated) | | ema://docs/knowledge-publish | Knowledge publish guide (metadata, scopes) | | ema://docs/feedback-confidence-pipeline | Feedback -> confidence scoring data flow | | ema://docs/vertex-ai-search-integrations | Discovery Engine integrations reference | | ema://catalog/agents-summary | Action catalog summary | | ema://catalog/patterns | Workflow wiring patterns | | ema://rules/anti-patterns | Common workflow mistakes | | ema://rules/extraction-column-format | Dashboard extraction column wiring | | ema://guidance/rules | Structured rules as JSON | | ema://guidance/cursor-rule | Export as Cursor .mdc rule | | ema://guidance/server-instructions | Server instructions text |

Environment Variables (Legacy)

Environment variables still work for authentication but are no longer the primary method. Use config(method="login") instead for a better experience with tenant-aware profiles.

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

Config File Locations

| Platform | Config File | | ------------------------ | ----------------------------------------------------------------- | | Cursor | ~/.cursor/mcp.json | | Claude Desktop (Mac) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Code | Managed via claude mcp add command | | VS Code | .vscode/mcp.json (workspace) or user settings | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

CLI

ema personas list                            # List personas
ema sync persona "My Bot" --target dev --dry-run  # Sync a persona
ema sync status                              # Check 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!,
});

const personas = await client.getPersonasForTenant();
const persona = await client.getPersonaById("uuid");
const templates = await client.getPersonaTemplates();
const actions = await client.listActions();

Installation (Alternative Methods)

Most users should use the npx command in their AI tool config (see Quick Start). These are for developers and advanced use cases.

Global install: npm install -g @ema.co/mcp-toolkit then run ema-mcp

Clone & build:

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

Troubleshooting

"No active profile" or "auth: missing"

Problem: You haven't logged in yet, or your session expired.

Fix: Tell your AI assistant: "Login to Ema". A browser window opens for you to authenticate via SSO.

"Browser automation not available"

Problem: Playwright is not installed, so the automatic browser login can't run.

Fix:

1. Install Playwright: npm install -g playwright && npx playwright install chromium
2. Or use the paste-token fallback -- the toolkit will guide you through it when Playwright isn't available

"OAuth credential expired or missing"

Problem: Your authentication token has expired (tokens last ~24 hours).

Fix: Say "Login to Ema" again. The browser opens, you authenticate, and a fresh token is stored.

Server not starting

Problem: The MCP server failed to launch.

Fix:

1. Verify Node.js: node --version (need 18+)
2. Test manually: npx -y @ema.co/mcp-toolkit@latest --help
3. Check for JSON syntax errors in your config file (missing commas, brackets)
4. Restart: Cmd+Shift+P -> "MCP: Restart Server" -> "ema"

"Cannot find module" or npm errors

Problem: npx cache might be stale.

Fix:

npx clear-npx-cache
npx -y @ema.co/mcp-toolkit@latest --help

Knowledge search not working

Problem: knowledge() returns no results or falls back to keyword-only mode.

Fix:

1. Install gcloud CLI: brew install google-cloud-sdk (Mac) or see cloud.google.com/sdk/docs/install
2. Authenticate: gcloud auth login (use your @ema.co Google account)
3. Verify: gcloud auth print-access-token should return a token
4. If using MCP in a sandboxed environment where gcloud can't exec, set EMA_GCP_ACCESS_TOKEN manually:

   export EMA_GCP_ACCESS_TOKEN=$(gcloud auth print-access-token)

Note: GCP tokens expire after ~1 hour. The toolkit attempts to refresh automatically via gcloud, but sandboxed environments may need the env var approach.

Multiple profiles not showing

Problem: You've logged into multiple environments but only see one.

Fix: Ask "show my profiles" or call config(method="profiles") to list all profiles. Use config(method="use", profile="name") to switch.

Legacy Authentication

If you prefer not to use browser-based login, you can still authenticate using environment variables. This method requires manually extracting a bearer token from the Ema web app.

Get Your Bearer Token

1. Log in to your Ema environment:

| Environment | URL | | ----------- | ---------------------------------------- | | Production | app.ema.co | | Demo | demo.ema.co | | Dev | dev.ema.co | | Staging | staging.ema.co |

2. Open browser DevTools:

| OS | Shortcut | | ------------- | --------------------------- | | Mac | Cmd + Option + I | | Windows/Linux | F12 or Ctrl + Shift + I |

3. Copy the bearer token:

1. Click the Network tab in DevTools
2. Refresh the page (so new requests appear)
3. Click on any request in the list
4. Look for the Authorization header in the "Headers" panel
5. Copy the value -- keep only the part after "Bearer "

                       +-- Copy everything AFTER "Bearer "
                       |
Authorization: Bearer your-token-goes-here

Note: Tokens expire after ~24 hours. When you get authentication errors, repeat this step for a fresh token.

Save Your Token

Add the token to your shell profile so it persists across sessions.

Mac/Linux -- edit ~/.zshrc (or ~/.bashrc):

# Open the file in a text editor
nano ~/.zshrc

Add these lines at the bottom (replace with your actual tokens):

# Ema MCP Toolkit tokens
export EMA_DEMO_BEARER_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
export EMA_PROD_BEARER_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Save the file (Ctrl+O, then Ctrl+X in nano), then reload:

source ~/.zshrc

Windows -- use PowerShell:

[Environment]::SetEnvironmentVariable("EMA_DEMO_BEARER_TOKEN", "eyJ...", "User")
[Environment]::SetEnvironmentVariable("EMA_PROD_BEARER_TOKEN", "eyJ...", "User")

Tip: You only need tokens for environments you actually use. One token is enough to get started.

Configure with Environment Variables

When using legacy auth, add an "env" block to your MCP server config:

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

The toolkit auto-detects environments from EMA_<ENV>_BEARER_TOKEN environment variable patterns.

Need Help?

• In your AI tool: Just ask! The toolkit includes built-in guidance. Try: "How do I create a voice persona?"
• GitHub Issues: github.com/Ema-Unlimited/ema-mcp-toolkit/issues
• Ema Support: Contact your Ema account team

License

This project is dual-licensed:

• AGPLv3 for open-source use
• Commercial license for proprietary, hosted, or closed-source use

If you intend to run this software in production, expose it over a network, or integrate it into a proprietary system, you must either comply with AGPLv3 or obtain a commercial license.

See LICENSE and LICENSE-COMMERCIAL.md for details.