Skip to main content

​
When to use API-key authentication

The standard Enginy MCP flow is user-granted OAuth 2.0 Authorization Code + PKCE, which requires an interactive browser sign-in. Server-side integration platforms — MuleSoft’s MCP Connector, backend agents, schedulers, and other machine-to-machine clients — cannot run that browser dance. For those clients, Enginy MCP also accepts a static workspace API key: the same key that authenticates the Enginy REST API. The MCP tool surface is generated from the same public API, so an API key grants the same operations over MCP that it already grants over REST — just on a different transport.
If your client can run an interactive OAuth flow (Claude, Codex, Cursor, VS Code, …), prefer the standard per-user sign-in — see the Client support matrix. API keys are for clients that cannot.

​
Requirements

  1. MCP enabled for the workspace. A workspace admin must activate the MCP policy in Enginy settings — the same switch that governs OAuth MCP connections. Without an active policy, API keys are rejected for MCP access (they keep working for the REST API).
  2. An API key. Create one in Enginy under workspace settings → API keys. Scope it to the least access the integration needs.

​
How to connect

Attach the key to every request to https://openapi.enginy.ai/mcp using either header — both are equivalent:
Quick smoke test:

​
MuleSoft MCP Connector

In the MCP Connector’s Streamable HTTP client connection, add a default request header:
  • Header name: Authorization, value: Bearer ${enginy.api.key} (or use x-api-key)
No OAuth Client ID / Client Secret configuration is needed — leave the connector’s OAuth section empty and rely on the static header. Because the key does not expire, there is no token refresh to manage.

​
How authorization works

  • The MCP session acts as the user who created the API key — tool calls read and write on that user’s behalf, and mcp_whoami reports that identity.
  • The key’s REST scopes are mapped to their MCP scope equivalents, then trimmed to the workspace MCP policy ceiling. A key with full access in a workspace whose MCP policy is read-only gets a read-only MCP session.
  • Revoking the API key, freezing the workspace, or deactivating the MCP policy immediately ends MCP access for the key.

​
Limitations

  • Read-only support impersonation, partner multi-account switching, and other admin tools are never available on API-key sessions — they require a user-granted OAuth connection.
  • The key is a long-lived credential. Store it in your platform’s secret manager, scope it minimally, and rotate it if it may have leaked.

​
Troubleshooting