Connect Grace to your editor.

Before you start

• A Grace account. The one you use at app.agent-grace.com. Signing in from your editor uses the same login, Google or GitHub included.
• An editor that speaks MCP over HTTP with OAuth. Claude Code, Cursor and the Claude app all do.
• For impact maps and reviews, a copy of the code. Recalling decisions, writing them down and getting a fix plan work straight away. Tracing what a change touches and checking a change need the app connected to its repository and audited once. Your assistant can do both from the editor, in your first session.

Connect your editor

One address for every editor. Nothing to download, no key to copy: the sign-in opens in your browser.

https://api.agent-grace.com/mcp

Claude Code, with the guardianRecommended

The Grace Guardian plugin connects the server and adds the hooks that let Grace speak up on its own: before an edit, before a commit, before your assistant finishes. It brings its own connection, so this is the whole setup. In Claude Code:

/plugin marketplace add Beyond-The-Brackets/grace-guardian
/plugin install grace-guardian@grace

Then quit and reopen Claude Code, run /mcp, pick grace and sign in when your browser opens.

No /plugin command where you work, for example in the Code tab of the Claude desktop app? Paste this to your assistant instead. It merges two keys into ~/.claude/settings.json itself, keeping everything already in the file:

Set up Grace on this project. Do all of it yourself, and do not assume I have the `claude` command on my PATH.

1. Open ~/.claude/settings.json (create it as {} if it is not there). Parse it, keep everything already in it, and merge in these two entries, then write it back. Do not replace the file:

{
  "extraKnownMarketplaces": {
    "grace": {
      "source": {
        "source": "github",
        "repo": "Beyond-The-Brackets/grace-guardian"
      }
    }
  },
  "enabledPlugins": {
    "grace-guardian@grace": true
  }
}

2. Tell me to quit and reopen Claude Code, then run /mcp and sign in to grace with my Grace account.

3. When I come back after that, connect this repository to Grace and tell me what Grace already knows about it.

Those two keys, for anyone who would rather edit the file by hand. Merge them; never replace the file with them alone.

{
  "extraKnownMarketplaces": {
    "grace": {
      "source": {
        "source": "github",
        "repo": "Beyond-The-Brackets/grace-guardian"
      }
    }
  },
  "enabledPlugins": {
    "grace-guardian@grace": true
  }
}

If /mcp then lists two grace servers, you had added one by hand before. Remove that one with claude mcp remove grace: the plugin brings its own.

Claude Code, tools only

Every tool, without the hooks. Grace answers when your assistant calls it, and says once a day that the guardian is not installed.

claude mcp add --transport http grace https://api.agent-grace.com/mcp

Then /mcp, pick grace and sign in. To share it with your team, check it into the repository instead:

{
  "mcpServers": {
    "grace": {
      "type": "http",
      "url": "https://api.agent-grace.com/mcp"
    }
  }
}

Cursor

1. 1.Open Cursor Settings, go to the MCP section and add a new server.
2. 2.Choose the HTTP type and paste the server address as the URL.
3. 3.Sign in when your browser opens.

Or declare it in .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of them:

{
  "mcpServers": {
    "grace": {
      "url": "https://api.agent-grace.com/mcp"
    }
  }
}

Cursor gets every tool. The guardian that steps in on its own runs in Claude Code only, for now: in Cursor, ask your assistant for a review with Grace before you commit.

Claude app and claude.ai

1. 1.Open Settings, then Connectors, then Add custom connector.
2. 2.Name it Grace and paste the server address as the URL. Leave the advanced settings empty and click Add.
3. 3.Click Connect. The Grace sign-in page opens.

Custom connectors need a Claude Pro, Max, Team or Enterprise plan. Grace answers when you ask it to; the guardian lives in Claude Code.

Other clients

Any client that speaks MCP over Streamable HTTP with OAuth works. Give it the server address and it discovers the rest: an unauthenticated request gets a 401 whose WWW-Authenticate header points at the server's protected-resource metadata (RFC 9728), and the client takes the sign-in from there.

CI and scripts

An editor never needs a key. Keys exist for places that cannot open a browser to sign in, such as a CI job or a script, and are created in the Grace app on the Connect Grace page. A key is shown once, opens the whole account, can never create another key, and stops working the moment it is revoked. Keep the file that holds it out of Git. To wire one into your pipeline, write to hello@agent-grace.com.

Grace is not published on npm. Nothing you install with npx is Grace, whatever it is called, so never hand a Grace key to one.

Check the connection

Open your project and ask your assistant:

>What does Grace know about this project?

It answers with the app it matched and what Grace holds on it. The Connect Grace page in the Grace app turns green the first time Grace hears from your editor, and from then on shows when it last did.

If Grace cannot tell which app the folder is, it lists your apps and asks rather than guessing. A wrong guess would feed your assistant another project's conventions, and nothing in the answer would give it away. Connecting the folder settles it: see the first step below.

Your first session

What to say, in your own words, and what happens behind it.

1. 01“Connect this repository to Grace.”

   Your assistant reads the Git remote and calls grace_connect_repo. A folder with no remote goes to grace_connect_local instead. Calling either twice is safe.

2. 02“Audit this codebase with Grace.”

   Grace runs its analysers and hands your assistant a work order. Your assistant reads the code on your machine, then sends its findings back with grace_audit_submit. Grace checks them, scores the app and writes its memory. Expect a few minutes of reading.

3. 03“What should we fix first?”

   grace_health returns the last audit in plain language, then grace_verify_findings checks each point against your current commit before anything is repeated to you.

4. 04“Add a billing page.”

   From here on, work as usual. Grace plans the change, recalls what the project decided, and asks for a review before the commit.

The guardian

Connected as a plain server, Grace is a tool your assistant may call. With the Claude Code plugin, it is consulted at each of these moments whether the assistant thinks of it or not.

Session starts

How the project stands, the areas that break, the debt that is there on purpose.

You send a prompt

Pushes back on the request itself before work starts, then adds what the team already decided about it, including approaches tried and rejected.

You leave plan mode

Reads the plan against the project: the settled decisions it crosses, the open issues in its files, how an irreversible step is undone, how anyone will know it worked.

Before a file is written

Refuses a credential about to land in code. Asks before an edit in a fragile area, a lockfile or an env file. Recalls what the project remembers about that file.

After a file is written

Reads it on the spot. A swallowed error, a muted test, a silenced type check, a second copy of a helper: said within the second, not at the end of the turn.

Before a shell command

Refuses git commit and git push while changed files are unreviewed. Asks before anything hard to undo: push --force, rm -rf, prisma migrate reset, curl … | sh.

Before the assistant finishes

Asks once for a review of what changed. Your assistant reviews with its own model; Grace scores what is new.

The checks on files, commands and commits are rules, not a model: they cost nothing and answer within a few seconds. Grace speaks only when it knows something about this project that the file does not show. It does not repeat what any competent engineer already knows.

Strictness

A team setting, changed by an owner or an admin on the Connect Grace page of the Grace app.

When Grace cannot be reached

The plugin fails closed. When Grace is unreachable, an edit is refused rather than let through unchecked, because “not checked” must never look like “nothing to report”. At session start a small check says whether Grace is reachable. To carry on knowingly while it is down, start Claude Code with GRACE_GUARD_FAIL_OPEN=1.

Turning it off

/plugin uninstall grace-guardian removes it. To silence it in one repository only, set "disableAllHooks": true in that repository's .claude/settings.local.json.

Tool reference

The server exposes 31 tools. Your assistant picks them from their descriptions, which say when to call each one; you never need to name them. They are listed here so you know what it can ask, and can recognise them in your editor's logs.

Project memory

What your team knows and the code does not say, kept in the repository where everyone can read it.

When you tell your assistant something worth keeping, grace_remember records it in Grace and returns a markdown note for your assistant to write under .grace/memory/. Plain files with frontmatter and [[wikilinks]]: readable in your editor, in code review on GitHub, and by anyone who clones the repository. Commit them. That is how the memory becomes the team's and not just yours.

decision

What was chosen, and why.

convention

How the code here is written.

sensitive_zone

An area that breaks often.

accepted_debt

A shortcut that is there on purpose.

incident

Something that went wrong, and what it taught.

rejected_approach

What was tried and dropped, so nobody tries it again blind.

---
type: accepted_debt
summary: "The invoice export is synchronous on purpose"
source: human
createdAt: 2026-09-01T10:00:00.000Z
refs:
  - "src/billing/export.ts"
---

# The invoice export is synchronous on purpose

We tried a queue. The ops burden was not worth it for 40 invoices a month.

Notes are append-only. One that turns out to be wrong is closed, not rewritten: the reasoning behind a past decision is exactly what stops someone making the same mistake again.

What Grace sees

Grace reads the repository, not your machine.

A connected app is read through its GitHub connection. Grace has no access to your disk: anything else comes from your assistant, which decides what to send.

Reviews send the change, not the files.

A diff and a fingerprint per file. Grace rebuilds the file from its own copy of the repository and refuses to review bytes that do not match.

The guardian sees the moment.

With the Claude Code plugin, each prompt, plan, edit and shell command passes through Grace as it happens, with the folder it happens in. That is how a credential is refused before it lands.

Secrets stay put.

Grace refuses .env files, lockfiles, binaries, node_modules and build output even if they are sent, and the review names what it left out.

The account comes from the sign-in.

Identity is read from the OAuth token, never from a tool argument, so neither an assistant nor a prompt injection can switch accounts by asking.

A local app sends no code.

grace_connect_local registers a name, a stack and a sentence. That app's audits run on your machine: your assistant reads, Grace scores.

The guarantees that hold beyond the editor, from pull requests you approve to how each account is isolated, are on Trust & Control.

Behaviour worth knowing

Silence is never approval.

"Unavailable", "never audited" and a timeout all mean not checked, and Grace says so. It does not stay quiet in a way that reads as "all good".

Long jobs hand back an id.

Editors cut a tool call at 60 seconds, so anything slower (an audit brief, an impact map, a review) answers within about 25 seconds with an id. Your assistant calls the same tool again with that id; starting a second job would redo the work.

Findings are dated, not tied to a commit.

The code may have moved since the last audit. grace_verify_findings checks each point against HEAD before it is repeated to you.

A review is a change, not a codebase.

grace_review takes up to 40 files. Beyond that it is an audit.

A loop gets paused.

When an editor sends more requests in five minutes than a person could, Grace pauses and says so. The guardian's hooks have their own, larger budget, so a review is never blocked by them.

Troubleshooting

Grace says it does not know this folder.

Ask your assistant to connect it. A GitHub repository goes to grace_connect_repo, a folder with no remote to grace_connect_local. If the app already exists and only the guardian is unsure, grace_guard_bind settles it once.

The guardian went quiet.

Hooks cannot renew an expired sign-in, and a dead connection fails silently in Claude Code. Run /mcp, pick grace and reconnect. The Connect Grace page in the app shows when Grace last heard from each member of your team.

Edits are refused with "Grace guardian is unreachable".

The plugin fails closed: an edit it cannot check is refused rather than let through unchecked. Reconnect with /mcp. To carry on knowingly while Grace is down, start Claude Code with GRACE_GUARD_FAIL_OPEN=1.

/mcp lists two grace servers.

You added one by hand before installing the plugin, which brings its own. Remove the manual one: claude mcp remove grace.

Impact maps and reviews say they cannot trace anything.

Grace needs a copy of the code first: the app connected to its repository and audited once. Ask your assistant to audit it with Grace.

The Claude app has no Add custom connector button.

Custom connectors need a Claude Pro, Max, Team or Enterprise plan.

Under --dangerously-skip-permissions, nothing asks me anything.

Nobody is there to answer an "ask", so Grace says so in context. In Strict mode those become refusals.

Still stuck? Write to hello@agent-grace.com with what your editor printed.