Setup

This guide walks you through connecting to the emma MCP Server, a remote server hosted by emma — there’s no local package to install.

Prerequisites

Before you begin, make sure you have:

One of the supported clients: Cursor, Claude Code, or Codex
An emma account
An emma API Key (create one from API Keys in the emma dashboard)

Step 1: Get Your API Key

Log in to emma
Go to API Keys
Click Create API Key and copy the generated key (it starts with emma_sk_)

Treat your API key like a password. Never commit it to version control or share it publicly.

Step 2: Configure Your Client

emma exposes its MCP server over Streamable HTTP at:

https://app.emma.ai/api/v1/mcp

Authenticate by sending your API key as a bearer token: Authorization: Bearer YOUR_API_KEY.

Cursor
Claude Code
Codex

Edit ~/.cursor/mcp.json (or use Cursor Settings → MCP to add a server):

{
  "mcpServers": {
    "emma": {
      "url": "https://app.emma.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Then restart Cursor to load the MCP server.

Claude Code can add a remote HTTP MCP server directly from the CLI:

claude mcp add --transport http emma \
  "https://app.emma.ai/api/v1/mcp" \
  --header "Authorization: Bearer YOUR_API_KEY"

Or edit .mcp.json in your project manually:

{
  "mcpServers": {
    "emma": {
      "type": "http",
      "url": "https://app.emma.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Edit ~/.codex/config.toml:

[mcp_servers.emma]
url = "https://app.emma.ai/api/v1/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Replace YOUR_API_KEY with your actual emma API Key in every example above.

Alternative: Local stdio Bridge

If your MCP client only supports the stdio transport (or doesn’t support custom HTTP headers yet), use emma’s local Node.js bridge instead. It proxies the same tools to the same backend over your API key.

{
  "mcpServers": {
    "emma": {
      "command": "npx",
      "args": ["-y", "@duzzle/emma-mcp"],
      "env": {
        "EMMA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

The local bridge is published on npm as @duzzle/emma-mcp and requires Node.js 18+. It exposes the exact same tool set described in emma MCP Server.

Verify the Connection

To verify that the emma MCP Server is working correctly, use the health check tool:

Open your client’s AI chat
Ask: “Check emma connection status”
The emma_health_check tool should report that the connection is healthy and your API key is valid

Configuration Reference

Setting	Value
Remote MCP URL	`https://app.emma.ai/api/v1/mcp`
Transport	Streamable HTTP
Authentication header	`Authorization: Bearer <api_key>` (also accepts `X-API-Key: <api_key>`)
Local bridge package	`@duzzle/emma-mcp` (npm), requires `EMMA_API_KEY` env var

Troubleshooting

Connection Issues

401 Unauthorized / api_key_required

No API key was sent with the request. Double-check that your client config includes the Authorization: Bearer YOUR_API_KEY header (or X-API-Key) exactly as shown above.

401 Unauthorized / invalid_api_key

The API key is missing, malformed, or has been revoked. Generate a new key from API Keys in the emma dashboard and update your config.

429 Rate Limited

You’ve exceeded the request rate limit for your API key. Wait and retry — the response includes a Retry-After header.

Tools not appearing

Restart your client completely after editing the MCP config
Check the config file for JSON/TOML syntax errors
Verify the server name matches what your client expects (usually emma)
Confirm the URL has no trailing typos: https://app.emma.ai/api/v1/mcp

Using the local stdio bridge instead

If npx -y @duzzle/emma-mcp fails to start, make sure Node.js 18+ is installed and EMMA_API_KEY is set in the env block of your MCP config.

Security Best Practices

Use Environment Variables

Where your client supports it, reference an environment variable instead of hardcoding the key in a committed config file.

Scope and Name Your Keys

Give each API key a descriptive name per machine/agent so you can revoke individual keys without affecting others.

Rotate Keys Regularly

Periodically create new API keys and revoke old ones from API Keys in the emma dashboard.

MCP

Prerequisites

Step 1: Get Your API Key

Step 2: Configure Your Client

Alternative: Local stdio Bridge

Verify the Connection

Configuration Reference

Troubleshooting

Connection Issues

Security Best Practices

Next Steps

emma MCP Server

Tools Reference

​Prerequisites

​Step 1: Get Your API Key

​Step 2: Configure Your Client

​Alternative: Local stdio Bridge

​Verify the Connection

​Configuration Reference

​Troubleshooting

​Connection Issues

​Security Best Practices

​Next Steps

emma MCP Server

Tools Reference

Prerequisites

Step 1: Get Your API Key

Step 2: Configure Your Client

Alternative: Local stdio Bridge

Verify the Connection

Configuration Reference

Troubleshooting

Connection Issues

Security Best Practices

Next Steps