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

# Connect Claude Code

> Register the hosted Enginy MCP server in Claude Code.

## Before you start

If you are not technical, this is the recommended place to start.

Claude Code works best with a fixed callback port, because Enginy can then allowlist one stable redirect URI instead of a random port.

Use this redirect URI in Enginy:

```text theme={null}
http://localhost:3118/callback
```

An Enginy admin should configure these workspace settings first:

1. Enable the MCP integration.
2. Add `http://localhost:3118/callback` to **Allowed redirect URIs**.
3. Leave **Allowed OAuth client IDs** empty for the first connection unless you intentionally want to pin trusted clients.
4. Choose the MCP policy scopes Claude Code is allowed to request.

<Tip>
  Leave the client-ID allowlist empty during initial setup unless your security policy requires pinning. Once
  you know the exact client ID your team uses, you can tighten the policy later.
</Tip>

## Add the hosted server

Run:

```bash theme={null}
claude mcp add --transport http --callback-port 3118 enginy https://openapi.enginy.ai/mcp
```

Then start Claude Code and open the MCP manager:

```text theme={null}
/mcp
```

Select `enginy` and start authentication.

## Complete the browser flow

When the browser opens, Enginy validates:

* the `redirect_uri` against your workspace allowlist
* the requested scopes against your MCP policy ceiling
* the optional `client_id` allowlist, if your workspace uses one

Approve the request and return to Claude Code after the browser lands on:

```text theme={null}
http://localhost:3118/callback?...
```

That callback page is usually served by Claude Code's local receiver, not by Enginy. Seeing a success screen there usually means the code exchange completed.

## Verify the connection

After authorization, ask Claude Code to use Enginy MCP and run:

```text theme={null}
mcp_whoami
```

That verifies:

* the hosted MCP server is reachable
* OAuth completed successfully
* Claude Code is sending the correct bearer token
* the granted scopes match what Enginy approved

## Advanced: local development

You can ignore this section unless your team is testing a local Enginy environment.

If you are running the local OpenAPI service, the MCP URL defaults to:

```text theme={null}
http://127.0.0.1:8081/mcp
```

A local setup typically needs:

* the OpenAPI service running
* the API OAuth routes running
* an Enginy frontend you can sign into for the browser approval step
* the same callback URI allowlisted in the workspace settings

Example local registration command:

```bash theme={null}
claude mcp add --transport http --callback-port 3118 enginy-local http://127.0.0.1:8081/mcp
```

## Common Claude Code issues

### `redirect_uri is not allowed`

The callback URI in Claude Code must exactly match one of the workspace allowed redirect URIs. With `--callback-port 3118`, that means:

```text theme={null}
http://localhost:3118/callback
```

### `OAuth client_id is not allowed`

Your workspace is pinning trusted client IDs and Claude Code's client ID is not on the allowlist. Either add that exact client ID or temporarily remove the allowlist while you establish the first connection.

### `Requested scopes are not allowed`

Claude Code requested a scope set outside the workspace policy ceiling. Reduce the requested scope set or expand the policy in Enginy.

### `needs authentication` or `Cannot POST /token`

This usually means the client tried a shorthand token path. Enginy supports both the canonical token endpoint and common compatibility aliases, so if you still see this error, you are usually hitting a stale server, a proxy, or the wrong base URL.

### No active connection appears in Enginy

Check that:

* MCP is enabled for the workspace
* the policy is active and has at least one scope
* the OAuth flow completed all the way through the browser callback
* the token exchange did not fail after the consent screen