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

# Overview

> Understand how Enginy MCP works, how tools are generated, and how OAuth and policy enforcement fit together.

## What Enginy MCP is

Enginy MCP lets an AI assistant connect to your Enginy workspace and use Enginy actions safely through a shared tool layer.

In plain English, that means the assistant can help with work like:

* looking up contacts, companies, campaigns, and inbox threads
* summarizing what is happening in Enginy
* preparing updates or changes for a human to review

The hosted resource server is:

```text theme={null}
https://openapi.enginy.ai/mcp
```

Behind the scenes, the server follows the same general remote-MCP model used by products like Linear and Notion:

* Streamable HTTP transport instead of local stdio
* OAuth 2.0 Authorization Code + PKCE for public clients
* Short-lived bearer access tokens plus rotating refresh tokens
* Workspace policy controls that cap what any user can grant

<Info>
  Enginy currently supports remote Streamable HTTP only. If your client only supports stdio, use a remote
  bridge such as `mcp-remote` or another client-side proxy that can speak remote MCP on your behalf.
</Info>

## How Enginy builds MCP tools

Enginy does not maintain a separate hand-written MCP catalog. Instead, the MCP server reads Enginy's public API document and turns supported API operations into MCP tools.

Today that means:

* `GET`, `POST`, `PATCH`, `PUT`, and `DELETE` OpenAPI operations can become tools
* the tool name comes from the OpenAPI summary when possible, with a method-and-path fallback if needed
* path params are exposed as `pathParams`
* query string params are exposed as `query`
* JSON request bodies are exposed as `body`
* the tool inherits its required scopes from the `**Required scope:**` metadata in the OpenAPI description

Enginy also exposes one native MCP tool:

* `mcp_whoami`, which returns the authenticated user, client, and granted scopes

## Advanced: what a tool call looks like

For OpenAPI-derived tools, the input shape is consistent:

```json theme={null}
{
  "pathParams": {
    "id": "123"
  },
  "query": {
    "limit": 25,
    "includeArchived": false
  },
  "body": {
    "name": "Example"
  }
}
```

Only include the sections that the tool actually needs. A read-only list endpoint might use only `query`, while a mutation might need `pathParams` and `body`.

Most users do not need to think about this. It is mainly useful if your team is debugging a client or building its own MCP experience.

## Connection model

<Steps>
  <Step title="An admin turns MCP on for the workspace">
    In Enginy, an admin enables MCP, decides which callback URLs are allowed, and chooses the maximum
    permissions users are allowed to approve.
  </Step>

  <Step title="A user connects from an AI interface">
    Claude Code or another compatible interface is pointed at `https://openapi.enginy.ai/mcp` and starts the
    browser sign-in flow.
  </Step>

  <Step title="Enginy checks that the request is allowed">
    Enginy verifies the callback URL, the requested permissions, and any optional client-ID restrictions
    before allowing the connection.
  </Step>

  <Step title="The AI interface finishes sign-in">
    The interface exchanges the authorization result for access tokens. Those tokens are short-lived and are
    refreshed automatically when supported.
  </Step>

  <Step title="Every tool call is checked again">
    Each time the assistant tries to use Enginy, the server checks that the connection is still valid and that
    the requested action is allowed under the current workspace policy.
  </Step>
</Steps>

## Admin controls vs user controls

| Control surface          | Who owns it                    | What it changes                                                 |
| ------------------------ | ------------------------------ | --------------------------------------------------------------- |
| MCP enabled/disabled     | Workspace admin                | Whether the workspace can use Enginy MCP at all                 |
| Allowed redirect URIs    | Workspace admin                | Which OAuth callback URLs can complete authorization            |
| Allowed OAuth client IDs | Workspace admin                | Which client IDs are trusted if you choose to pin them          |
| Policy scopes            | Workspace admin                | The maximum permission ceiling any user can grant               |
| OAuth approval           | Individual user                | The exact subset of scopes approved for that user connection    |
| Connection revocation    | Admin or system policy changes | Whether a specific user connection or token chain remains valid |

## Important things to know

* Write permissions also include the matching read permissions. For example, `CONTACTS_WRITE` also includes contact reads.
* If a client asks for no explicit permissions, Enginy grants the full current workspace policy ceiling.
* If an admin tightens the policy later, an existing connection may stop working until the user connects again with the new limits.
* Enginy is a hosted remote MCP server, not a local stdio server.
* Refresh-token reuse is treated as a security problem and revokes the connection.

<CardGroup cols={2}>
  <Card title="Connect Claude Code" icon="terminal" href="/mcp/claude-code">
    Start here if you want the clearest setup path for a non-technical team.
  </Card>

  <Card title="Clients & interfaces" icon="code" href="/mcp/custom-clients">
    See the setup options for Claude, Codex, Cursor, VS Code, ChatGPT, and other remote clients.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Client support matrix" icon="table-list" href="/mcp/client-support-matrix">
    Compare which interfaces are the safest first choice and which ones need more technical setup.
  </Card>

  <Card title="Supported tools" icon="list-check" href="/mcp/supported-tools">
    See the kinds of work Enginy MCP can help with today.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Example prompts" icon="message-lines" href="/mcp/example-prompts">
    Use example prompts that work well for research, summaries, and human-reviewed changes.
  </Card>

  <Card title="Scope reference" icon="shield-check" href="/mcp/scopes">
    Review the permission groups that decide what the assistant can read or change.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Security and troubleshooting" icon="triangle-exclamation" href="/mcp/security-troubleshooting">
    Learn the recommended security posture and how to debug the most common failures.
  </Card>

  <Card title="FAQ / known limitations" icon="circle-question" href="/mcp/faq-known-limitations">
    Get quick answers about current constraints, unsupported assumptions, and when something is a bug.
  </Card>
</CardGroup>