Skip to main content

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.

​
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: 
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.
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.

​
Add the hosted server

Run: 
claude mcp add --transport http --callback-port 3118 enginy https://openapi.enginy.ai/mcp
Then start Claude Code and open the MCP manager: 
/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: 
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: 
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: 
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: 
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: 
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