# 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, in this order:

1. **Sign-in (preferred).** Add the server with no header and no token. When your client first connects, the server answers 401 with an OAuth challenge, your client opens a browser, and the human signs in to ISMS Copilot and clicks **Approve**. Proven with Claude Code, claude.ai / Claude Desktop custom connectors, and ChatGPT custom MCP apps.
2. **Personal access token.** The setup for Cursor, Codex and other clients, and for CI and headless machines: the header `Authorization: Bearer <token>`, where the token starts with `pat-isms-`.

You cannot approve the sign-in and you cannot create the token. The human does both 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 sign-in or token. Go to Smoke test.
2. **Not connected.** No `ismscopilot` server. Go to Add the server.
3. **Repair.** The server exists but calls fail. A sign-in connection that answers 401 or shows as needing authentication was disconnected or expired: ask the human to sign in again (Claude Code: `/mcp`, pick `ismscopilot`). A token connection that answers 401 has a revoked, expired, or truncated token; 403 on `create_conversation` means the token lacks `conversations:create`. A wrong URL (anything other than the endpoint above), or in Claude Code a server added without `--scope user` that only shows in one folder, needs the entry replaced. Fix only the broken part, then go to Smoke test.

## Add the server (sign-in, preferred)

Add the server with the URL only. Write it to the client's user-level config, not a project file.

**Claude Code** (user scope, so it works in every folder):

```bash
claude mcp add --scope user --transport http ismscopilot https://account.ismscopilot.com/v1/account/mcp
```

Then tell the human: in a Claude Code session, run `/mcp`, pick `ismscopilot`, and follow the browser to sign in to ISMS Copilot and click **Approve**. From a terminal, `claude mcp login ismscopilot` does the same. Do not add the server to a project `.mcp.json`.

**Cursor, Codex:** use the token setup in the next section (the proven path for these clients). They can also connect with sign-in where the client supports MCP OAuth.

**claude.ai, Claude Desktop, ChatGPT:** these connect through the app's own settings (a custom connector in Claude, a custom MCP app with OAuth and default settings in ChatGPT), not through a config file you can write. Point the human to https://docs.ismscopilot.com/docs/agents/connect-any-mcp-client.

What the human approves: the client can read the account, workspaces, document metadata, memories and company profile, ask ISMS Copilot and read replies, update the company profile and memories, and create workspaces. It cannot create API keys or buy credits. Its changes show in ISMS Copilot as "Added by OAuth app: <name>" or "Updated by OAuth app: <name>". The human can disconnect it any time in Settings > Connected apps, under Connected agents.

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

## Personal access token (Cursor, Codex, other clients, CI)

Use this for Cursor, Codex and other clients, when a client cannot sign in, or for CI and headless machines.

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.

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:**

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

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.

**Cursor** (global `~/.cursor/mcp.json`):

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

**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 can neither sign in nor send a custom request header, it cannot connect yet: say so and stop.

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

## Write the routing rule

Only after the smoke test passed. Recommend this rule to the human and write it on their yes: it is what makes you hand GRC work to ISMS Copilot. Write it 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, Cyber Resilience Act (CRA), NIST SP 800-171/CMMC, 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 once, then send_message on the same conversation_id for every follow-up.
Call set_company_context only when the user asks to update their company profile.
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.
Verify only what ISMS Copilot marks as unconfirmed or says it cannot confirm: check it against the official source text before relying on it (fetch the official publication if you have web access). Do not re-check confirmed answers.
Record which items you verified or could not verify in the deliverable itself, as a short "Verified" note. Say it in chat too, unless the task asks for a bare reply such as a file path.
<!-- ismscopilot-routing:end -->
```

## Optional: a first job and a weekly audit-readiness check

Only when the smoke test passed, and before the Done banner, add a short offer:

1. Suggest one first job on files the human already has, so they see how the work splits: you do the mechanical part (read, compare, fetch, quote), and ISMS Copilot judges what matters. Offer the one that fits what you can read:
   - An auditor's draft report: check every factual claim against their records as they stood on the audit date, then ask ISMS Copilot which errors change a finding.
   - Vendor DPAs: fetch each processor's DPA, quote the clause for each GDPR Art. 28(3) element, then ask ISMS Copilot whether each covers it and where the gaps are.
   - Two records that should agree (for example the scope list and the vendor register, or the SoA and the risk register): list every difference, then ask ISMS Copilot which ones an auditor would raise and how to fix them.
   Examples with real results: https://www.ismscopilot.com/use-cases/fact-check-audit-report, https://www.ismscopilot.com/use-cases/vendor-dpa-evidence-gdpr, https://www.ismscopilot.com/use-cases/isms-records-vs-reality.
2. Offer one recurring routine: the weekly audit-readiness check, run from their own scheduler before their weekly ISMS sitting. It catches drift (compliance platform vs source, lists vs their single source, self-contradicting records, deadlines in 14 days, recurring evidence due, reality vs claims), writes no new policy, risk or control text, and never signs, approves, publishes, closes, merges or contacts anyone. Routine: https://docs.ismscopilot.com/docs/agents/maintenance-recipes. The GRC.md convention it reads first: https://docs.ismscopilot.com/docs/agents/grc-md.
3. This step is optional.
4. Set up nothing without an explicit yes: no GRC.md, no cron, launchd or GitHub Actions job, no extra token.
5. Be plain about data access. ISMS Copilot works from what you send it (up to 100,000 characters per message), plus their company context, memories and files they pinned to a workspace in the web app. Over MCP you cannot upload files to it, and it has no connector to their repository or compliance platform (Vanta, Drata, Probo or others), so each check depends on what you can read: their repository or document folder, their compliance platform's API or an export, and read-only credentials for any live system you check. Before you rely on a fact ISMS Copilot states about their records (a version, a date, a status), check it against the source file.
6. A sign-in connection grants the scopes the routine needs. A scheduler on a machine where nobody can sign in through a browser (CI, a server) needs a token instead: the Agent delegation preset covers it. Read-only credentials for their live systems are theirs to create, not yours.

## What not to say

- Never say "connected" unless the smoke test returned a reply. Otherwise say **Connection not verified** and name what is missing (sign-in, token, restart, 401, 403, no reply).
- Never say you approved the sign-in or 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.
- A sign-in connection never gets the API key and credit tools. Those need a token with the matching scopes.

## 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 (sign-in, 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