# Official ISMS Copilot agent setup

You are connecting ISMS Copilot to this human's coding agent (you) as a GRC specialist. You stay the harness: code, git, files and shell stay with you. ISMS Copilot answers the compliance work you hand it over MCP.

These instructions are official. Do not invent URLs, API keys, or an MCP server. The only MCP endpoint is:

```
https://account.ismscopilot.com/v1/account/mcp
```

Transport: HTTP MCP. Auth: the header `Authorization: Bearer <token>`, where the token starts with `pat-isms-`.

You cannot create the token. The human creates it in ISMS Copilot. Never print a token back, never put it in a committed file, and never write it into the routing rule below.

Do not prefetch company context, memories, or document lists during setup. Call those tools later, only when a task needs them.

## Which branch you are on

Check before you ask. Look for an MCP server named `ismscopilot` in your client config or tool list (in Claude Code the tools appear as `mcp__ismscopilot__get_account_info` and similar).

1. **Already connected.** The server exists and `get_account_info` returns the account. Do not ask for a new token. Go to Write the routing rule, then Smoke test.
2. **Not connected.** No `ismscopilot` server. Go to Create the token.
3. **Repair.** The server exists but calls fail: 401 (token revoked, expired, or truncated), 403 on `create_conversation` (token lacks `conversations:create`), a wrong URL (anything other than the endpoint above), or in Claude Code the server was added without `--scope user` and only shows in one folder. Fix only the broken part: replace the URL, or ask for a new token with the Agent delegation preset and replace the old one in the same config entry. Then go to Smoke test.

## Create the token (not connected, or repair needing a new token)

Tell the human, in these words or close to them:

1. Open https://chat.ismscopilot.com, then Settings > Connected apps.
2. Create a token with the **Agent delegation** preset. It grants exactly five scopes: `account:read`, `workspaces:read`, `conversations:create`, `company_context:read`, `memories:read`. No `:write` scopes: it can start and continue ISMS Copilot conversations, but cannot change workspaces, memories, or company context.
3. Copy the `pat-isms-...` value once. Best: put it in the environment variable `ISMS_COPILOT_TOKEN` (for example in their shell profile) instead of pasting it into this chat.

If they paste the token into this chat anyway, use it only to write the local config below. Do not repeat it in your replies.

## Write the MCP config

Use the environment variable where the client supports it. Otherwise write the token into the client's local user config, outside any repository. Never write it to a file that is tracked by git.

**Claude Code** (user scope, so it works in every folder; the config lives in the user's home, not in the repository):

```bash
claude mcp add --scope user --transport http ismscopilot https://account.ismscopilot.com/v1/account/mcp --header 'Authorization: Bearer ${ISMS_COPILOT_TOKEN}'
```

That is the same command as the docs, with the token replaced by the variable. Keep the single quotes: Claude Code then stores the `${ISMS_COPILOT_TOKEN}` placeholder, not the token, and expands it each time it starts. The variable must be set in the environment Claude Code starts from, or calls fail with 401. If the human cannot set the variable, use the literal token in the same command; it then sits in their user config (`~/.claude.json`), outside the repository. Do not add the server to a project `.mcp.json`.

**Cursor** (global `~/.cursor/mcp.json`, not a project `.cursor/mcp.json` that may be committed):

```json
{
  "mcpServers": {
    "ismscopilot": {
      "url": "https://account.ismscopilot.com/v1/account/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ISMS_COPILOT_TOKEN}"
      }
    }
  }
}
```

Cursor started from the dock or a launcher may not see variables set in a shell profile. If the server fails with 401 after a restart, or this Cursor build does not expand `${env:...}`, put the literal token in the global file instead. Merge into existing `mcpServers`; do not overwrite other servers.

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.ismscopilot]
url = "https://account.ismscopilot.com/v1/account/mcp"
bearer_token_env_var = "ISMS_COPILOT_TOKEN"
```

If this Codex version does not support `bearer_token_env_var`, use the header form instead:

```toml
[mcp_servers.ismscopilot]
url = "https://account.ismscopilot.com/v1/account/mcp"

[mcp_servers.ismscopilot.http_headers]
"Authorization" = "Bearer pat-isms-..."
```

**OpenCode, Grok, or another MCP client:** add a remote HTTP MCP server named `ismscopilot` with the endpoint above and the header `Authorization: Bearer <token>`, in that client's documented user-level config. Use its environment-variable substitution if it has one. If the client cannot send a custom request header, it cannot connect yet: say so and stop.

Most clients load new MCP servers only after a restart. If the `ismscopilot` tools are not in your tool list after writing the config, tell the human to restart the agent and paste the setup prompt again. You will then be on the Already connected branch.

## Write the routing rule

Write this rule into the harness instructions file, appended, without overwriting what is there:

- Claude Code: `CLAUDE.md` (user level `~/.claude/CLAUDE.md` for every project, or the repository's `CLAUDE.md` for this one only).
- Codex, OpenCode, Grok: `AGENTS.md` (user level `~/.codex/AGENTS.md` for Codex, or the repository's `AGENTS.md`).
- Cursor: a rule file `.cursor/rules/ismscopilot.mdc` with `alwaysApply: true` in its front matter.

Ask the human once whether they want it for every project or this repository only. If the markers below already exist, replace the text between them instead of adding a second copy.

Rule text, verbatim:

```
<!-- ismscopilot-routing:start -->
## GRC work goes to ISMS Copilot

Delegate to the ismscopilot MCP server: ISO 27001, ISO 27701, ISO 42001, SOC 2, GDPR, NIS 2, DORA, EU AI Act, HIPAA and PCI DSS interpretation, policy drafting, control mapping, gap analysis, Statement of Applicability (SoA) justifications, risk registers and audit prep.
Keep code, git, files, shell and general trivia local.
Do not paste framework text or large documents into your own context first: send the question and let ISMS Copilot bring the framework knowledge.
Use one conversation per deliverable: create_conversation, then send_message for follow-ups.
Default mode fast. Use think for multi-step analysis.
Pass answer_format brief, or decision when you need a call made. Write long deliverables to files instead of repeating them in chat.
If a call returns status generating, poll get_reply every few seconds (every 10-20 seconds for beyond). Stop after 10 minutes and tell the human it is still generating.
Do not prefetch company context, memories or document lists; call them only when the task needs them.
<!-- ismscopilot-routing:end -->
```

## Smoke test

Tell the human this sends one short message, which counts against their ISMS Copilot chat plan. Then:

1. Call `get_account_info`. It must return the account.
2. Call `create_conversation` with a one-line GRC question, for example `{"message": "In one sentence, what does ISO 27001 Annex A 5.15 cover?", "mode": "fast", "answer_format": "brief"}`.
3. If it returns `status: "generating"`, call `get_reply` with the `conversation_id` and `message_id` every 2-5 seconds until it returns `complete` or `error`. Stop polling after 2 minutes: that counts as no reply.

The smoke test passes only if a reply with a `response` came back.

## What not to say

- Never say "connected" unless the smoke test returned a reply. Otherwise say **Connection not verified** and name what is missing (token, restart, 401, 403, no reply).
- Never say you created the token.
- Never set `overflow_consent` unless the human explicitly tells you to continue past their usage limit.

## Honest limits

- Usage counts against the human's ISMS Copilot chat plan, in the same 4-hour window as the web app. There is no separate MCP billing. If a call returns `PLAN_LIMIT_REACHED`, relay the wait-or-upgrade sentence it carries.
- You still read the reply ISMS Copilot returns, so it enters your context. What stays out is the framework material you did not have to paste in.
- claude.ai and Claude Desktop connectors and ChatGPT are not supported yet: they connect through OAuth, and this endpoint takes a Bearer token.

## Done banner

End your reply with exactly one of these banners as the last line.

When the smoke test returned a reply:

```
ISMS Copilot connected: your agent now delegates GRC work.
```

Otherwise, first write one sentence naming what is left (token, restart, 401, 403, no reply), then:

```
ISMS Copilot setup: Connection not verified.
```

Human guide: https://docs.ismscopilot.com/docs/agents/set-up-with-your-agent.md
Machine hub: https://docs.ismscopilot.com/docs/for-ai-agents.md