# Connect your AI to Engramic

Engramic's MCP server is a **remote, OAuth-protected** server that speaks
streamable HTTP. Connecting is the same everywhere: add the server URL to your
AI client and complete an interactive sign-in. **There is no token or API key to
paste** — the browser sign-in grants access.

The server URL is:

```
https://api.engramic.ai/mcp
```

When you add the connector and sign in, you choose your workspace during the
sign-in — the connection is bound to it.

**For IT admins:** how the Engramic MCP server handles sign-in, permissions,
tools and data is documented at https://www.engramic.ai/docs/mcp/

## Claude Desktop

1. Open **Settings → Connectors**.
2. Choose **Add custom connector**.
3. Paste the URL above and confirm.
4. Sign in when the browser window opens, and pick your workspace.

Power-user fallback (editing `claude_desktop_config.json` directly): a bare
`url` is not valid there, so route it through `mcp-remote`:

```json
{
  "mcpServers": {
    "engramic": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.engramic.ai/mcp"]
    }
  }
}
```

## Claude.ai (web)

1. Go to **Settings → Customize → Connectors**
   (https://claude.ai/customize/connectors).
2. Choose **Add custom connector**.
3. Paste the URL above and confirm.
4. Sign in when prompted, and pick your workspace.

On **Team** and **Enterprise** plans, only an organisation owner or admin can add
a connector — via **Organization settings → Connectors**.

## Claude Code

Add the server from the command line, at user scope:

```bash
claude mcp add --transport http --scope user engramic https://api.engramic.ai/mcp
```

Then run `/mcp` inside a session to complete the OAuth sign-in.

### Install the Engramic plugin (recommended)

The plugin records key decisions and milestones from your Claude Code sessions
to Engramic (decisions are always shown to you before they are published) and
checks a repo's Engramic setup. From a terminal:

```bash
claude plugin marketplace add engramic-ai/claude-plugin
claude plugin install engramic@engramic-ai
```

Or inside a Claude Code session:

```
/plugin marketplace add engramic-ai/claude-plugin
/plugin install engramic@engramic-ai
```

Then start a new Claude Code session so the plugin's hooks and skills load, run
`/mcp` and sign in, picking your workspace. Optionally, run `/engramic:setup`
in a repo to check its Engramic setup and add per-repo defaults
(`.engramic.json`).

The plugin does not include its own MCP server, so the step above stays separate.
If Engramic's tools are already available (for example through the claude.ai
connector), skip the `claude mcp add` command. The hooks need Node 20 or later;
without Node, recording still works but the hooks and setup check do nothing.
Source: https://github.com/engramic-ai/claude-plugin (MIT).

Alternatively, add the server to `.mcp.json` (project-scoped, so it only applies
in that repo) — the `"type": "http"` line is **required**
(a bare `url` errors and the server is silently skipped):

```json
{
  "mcpServers": {
    "engramic": {
      "type": "http",
      "url": "https://api.engramic.ai/mcp"
    }
  }
}
```

## Other MCP clients (Cursor, VS Code, and more)

Add a **remote / streamable-HTTP** MCP server pointing at the URL above. The
client will open a browser to authenticate via OAuth. No token is required.

## Advanced — pin a workspace (optional)

Most people never need this: at sign-in you simply pick your workspace. But if
you run several projects or connections at once, you can **pin** a specific
workspace by appending `?ws=<workspace-slug>` to the server URL:

```
https://api.engramic.ai/mcp?ws=<workspace-slug>
```

Pinning lets the OAuth sign-in tell your connections apart, so each stays bound
to the workspace you intended. It is entirely optional.

## Set it up with your AI

The fastest path is to let your agent set itself up. Paste this one line into any
capable coding or chat agent — it will fetch the official instructions and add
the server for you (append `?ws=<slug>` to pin a specific workspace):

```text
Fetch https://app.engramic.ai/agent-setup/prompt.md
```

You'll still finish the browser sign-in yourself. Prefer to drive it by hand?
Paste the prompt below to any agent and let it walk you through the steps for
your specific client:

```text
I want to connect my AI client to Engramic's MCP server.
The server URL is: https://api.engramic.ai/mcp
It is a remote, streamable-HTTP, OAuth-protected MCP server — there is no token
to paste; connecting triggers an interactive browser sign-in where I pick my
workspace.
Full setup instructions live at: <THIS-PAGE-URL>
Please detect which MCP client I'm using and give me the exact steps to add this
server and sign in. Note that you cannot complete the browser sign-in for me — I
will do that step myself when the OAuth window opens.
```

An agent can add the server configuration for you, but it cannot complete the
OAuth browser sign-in on your behalf — you'll finish that final step yourself.