> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Server-to-Server (API key)

> Connect MuleSoft or another server-side MCP client to Enginy MCP with a static workspace API key — no browser OAuth flow required.

## 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](/api-reference/introduction). 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.

<Tip>
  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](/mcp/client-support-matrix). API keys are for clients
  that cannot.
</Tip>

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

```text theme={null}
Authorization: Bearer gsk_your-api-key
```

```text theme={null}
x-api-key: gsk_your-api-key
```

Quick smoke test:

```bash theme={null}
curl -s https://openapi.enginy.ai/mcp \
  -H "Authorization: Bearer $ENGINY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'
```

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

| Response                                                           | Meaning                                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `401` `Invalid API key`                                            | The key is unknown — check for whitespace or a truncated value.                            |
| `401` `API key is revoked`                                         | The key was revoked in Enginy settings; create a new one.                                  |
| `401` `MCP is not enabled for this workspace…`                     | An admin must activate the MCP policy in Enginy settings.                                  |
| `401` `API key scopes are not allowed by the workspace MCP policy` | The key's scopes and the MCP policy don't overlap — widen the policy or re-scope the key.  |
| A tool fails with `Tool requires scopes: …`                        | The key (or policy ceiling) lacks that scope group — see [Scopes and policy](/mcp/scopes). |