Troubleshooting and Limits

Most Ema MCP problems are about authentication or which environment you're connected to. This page lists the common symptoms and fixes, then the limits to keep in mind.

Common issues

Re-run the authentication step for your client: select Authenticate in /mcp (Claude Code), run codex mcp login <name> (Codex), or select Connect on the connector (Desktop app). If sign-in itself fails, confirm you have an Ema account with access to the environment you're connecting to, and that you're using the right credentials for that environment.

The connection refreshes automatically, so you normally stay signed in. If your client does prompt you to sign in again — after an extended period, or if your access was changed or revoked — re-authenticate the same way you connected: select Authenticate in /mcp (Claude Code), run codex mcp login <name> (Codex), or Connect on the connector (Desktop app).

No Ema tools appear

Confirm the connection is authenticated (/mcp should list it as authenticated).
Confirm your client supports streamable HTTP transport with OAuth, and that you added the server with the HTTP transport (not stdio).
Restart the client so it reloads the connection.

Wrong or missing AI Employees

If results look empty or unfamiliar, you're probably connected to the wrong environment or tenant. Ask "Who am I on Ema?" to check, then connect using the endpoint for the environment where your data lives (Dev, Staging, Prod, or Demo). Remember that each environment is separate.

Connection or authorization errors

Check that the server URL is exactly the environment endpoint, including the /api/v1/agent-harness/mcp path. If you're on a corporate network or VPN, confirm it allows access to the Ema environment. Then re-authenticate.

The Ema connector isn't listed (Desktop app)

Use the search box in Manage Connectors to find Ema Dev, Ema Staging, Ema Prod, or Ema Demo, and make sure your Desktop app is up to date.

Limits

Acts within your role and tenant. The MCP can't do anything your account can't; actions you're not permitted to take are refused, and resources outside your tenant aren't visible. See Capabilities.
One environment per connection. A connection is pinned to a single environment. Add a separate connection for each environment you need.
You stay signed in across sessions. Access is short-lived but the client refreshes it silently, so you don't re-authenticate each time — only after an extended period or if access is revoked. The server doesn't retain conversation context between sessions, so keep the details your assistant needs within the current conversation.
Changes are real and immediate. There's no separate "draft" sandbox for MCP actions beyond what the platform already provides (for example, workflow versions and publishing). Use Dev or Staging to experiment.

Getting help

If you're stuck after the steps above, see Support for how to reach the Ema team, and include the client you're using, the environment, and what you asked for.