The MCP server

groundrule mcp runs a Model Context Protocol server for your coding agent. It gives the agent two tools: list_standards reads the rules in effect in the repository, and propose_rule sends a rule to your team’s inbox for review. This page shows how to set it up in each agent, what each tool takes and returns, and how to fix common problems.

What MCP is

The Model Context Protocol (MCP) is a standard way for a coding agent to call tools outside itself. The agent starts the tool as a local program and exchanges JSON messages with it over standard input and output. Claude Code, Cursor, VS Code and many other agents support it.

Groundrule’s server is part of the CLI. It runs on your computer, in your repository, and needs no extra install:

npx -y @groundrule/cli mcp

You don’t run this yourself. You tell your agent to start it, and the agent talks to it.

Note

Agent instruction files (written by sync) and the MCP server work together. The files put the rules in front of the agent on every task. The server lets the agent look rules up on demand, and turn a correction you make into a proposal.

Set it up

The agent must start the server from inside the repository. The server reads .groundrule/config.yaml from its working folder, the same way the CLI does.

Claude Code

In your repository, run:

claude mcp add groundrule -- npx -y @groundrule/cli mcp

To share the server with everyone who works in the repository, add it to .mcp.json at the repository root and commit it:

{
  "mcpServers": {
    "groundrule": {
      "command": "npx",
      "args": ["-y", "@groundrule/cli", "mcp"]
    }
  }
}

Cursor

Create .cursor/mcp.json in the repository:

{
  "mcpServers": {
    "groundrule": {
      "command": "npx",
      "args": ["-y", "@groundrule/cli", "mcp"]
    }
  }
}

Cursor shows the server and its two tools in its MCP settings. Turn it on there if Cursor asks.

VS Code

Create .vscode/mcp.json in the repository. VS Code calls the list servers:

{
  "servers": {
    "groundrule": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@groundrule/cli", "mcp"]
    }
  }
}

Start the server from the file, or from the MCP server list, and allow it in agent mode.

Other agents

Any MCP client that can start a local (stdio) server works. Give it:

Setting	Value
Command	npx
Arguments	-y, @groundrule/cli, mcp
Transport	stdio
Working folder	The repository root

If the client can’t set a working folder, pass the repository with the CLI’s global -C option: npx -y @groundrule/cli -C /path/to/repo mcp.

You should see a server named groundrule with the tools list_standards and propose_rule. Ask your agent “Which Groundrule standards apply here?”. It should call list_standards and answer from the result.

If the agent shows the server as failed, see Troubleshooting below.

What you need

To use	You need
list_standards, offline mode	A .groundrule/config.yaml with extends (no platform). Nothing leaves your computer.
list_standards, connected workspace	A config with platform: and a valid sign-in: groundrule login, or GROUNDRULE_TOKEN in the agent’s environment. The server reads the rulebook from Groundrule, the same way sync does.
propose_rule	A config with platform: (or GROUNDRULE_TOKEN set), and a sign-in whose token can propose rules. groundrule login gives that permission. A token from Settings → API tokens needs Propose rules ticked.

Node.js 22 or later must be on the agent’s PATH, because the agent runs npx. See Install the CLI.

What the server tells the agent

When an agent connects, the server sends these instructions. Agents use them to decide when to call each tool:

Groundrule holds this team’s engineering standards. Call list_standards to see the rules in effect before writing or reviewing code, and follow them. When the developer corrects you about how code in this codebase should be written and says, or confirms when you ask, that it should apply to everyone from now on, call propose_rule so the team can adopt it. Never propose one-off preferences, rules that already exist, or anything the developer didn’t ask for or agree to.

In practice: the agent proposes a rule only when you’ve said, or confirmed, that it should apply to everyone.

list_standards

Lists the standards in effect in this repository. It is read-only.

Input

Field	Type	Required	What it does
query	string	No	Only standards whose ID, title, or requirement contain these words. Every word must match, in any order, ignoring case.

What it includes

• Standards whose status is active and that no config override disables.
• Only standards that apply to this repository (its languages, frameworks, tags and name).
• For a connected workspace: the organization’s rules at Teach, Advise and Enforce, plus your repository’s own standards in .groundrule/standards/. Observe rules and drafts aren’t included.

Rules are sorted by severity (blocker first), then by ID.

Output

The agent receives one line per standard:

ACME-004 (blocker · advise: findings warn, never fail) Route all Stripe calls through the gateway: Never import stripe outside src/payments/gateway.ts. Call the gateway's functions, such as createPaymentIntent, instead. [applies to src/**]
SEC-003 (blocker · enforce) No access tokens in code: Never hard-code cloud keys or API tokens (AWS, GitHub, Slack, Stripe live keys). Read them from the environment or a secret manager.

Each line has:

• the ID;
• in parentheses, the severity, and for an organization rule its stage note;
• the title, then the rule’s agent.summary if it has one, otherwise its requirement;
• [applies to …] when the rule has paths.

The stage notes are:

Stage	Note	What groundrule check does with findings
Teach	teach: guidance only	Doesn’t check it.
Advise	advise: findings warn, never fail	Shows them as warnings.
Enforce	enforce	Counts them at the rule’s severity.

Standards from offline packs and your own .groundrule/standards/ files have no stage, so the parentheses only hold the severity, for example ACME-004 (blocker).

When nothing matches, the text is No standards match "<query>"., or No standards are in effect in this repository. without a query.

Clients that read structured results also get the same data as JSON:

{
  "standards": [
    {
      "id": "ACME-004",
      "title": "Route all Stripe calls through the gateway",
      "severity": "blocker",
      "stage": "advise",
      "requirement": "Never import stripe outside src/payments/gateway.ts. Call the gateway's functions, such as createPaymentIntent, instead.",
      "paths": ["src/**"]
    }
  ]
}

stage appears only for organization rules, and paths only when the rule has them.

propose_rule

Sends one rule to your organization’s inbox. Nothing changes in the rulebook until a reviewer accepts it. See The review inbox.

Input

Field	Type	Required	Rules
rule	string	Yes	The rule as one clear sentence: what to do or never do. 10 to 1,000 characters after trimming.
why	string	No	Why, in the developer’s words. Up to 1,000 characters.
example	string	No	A short code example of the right or wrong way. Up to 2,000 characters.
file	string	No	Where it came up, as a path relative to the repository. Up to 400 characters. Absolute paths and .. are refused.
line	integer	No	A line in that file, 1 or more.

No other fields are accepted. A rule that is too short comes back as Not proposed: rule: Say the rule in a sentence.

What is sent

Only what the proposal contains leaves your computer:

• the five fields above;
• the repository name, from platform.repository in your config or from the origin git remote;
• the agent’s name, as its MCP client reports it (lowercased, for example claude-code).

No file contents are sent. Groundrule removes secrets from the text before storing it. The proposal is recorded as yours: it shows your name and the agent that sent it.

Results

Result text	What happened
Proposed to <workspace>. A reviewer will accept or reject it in the Groundrule inbox (<url>).	A new proposal is in the inbox.
Already proposed in <workspace>; this was added to it. A reviewer decides.	The same rule was proposed before. Yours counts as a vote.
Not proposed: reviewers in <workspace> already rejected this rule. Tell the developer; they can ask a reviewer to reopen it.	A reviewer rejected this rule earlier.
… Similar existing rules: ACME-004, SEC-003.	Added to any of the above when the rulebook has rules with similar wording.
Not proposed: <reason>	Nothing was sent, or the platform refused it. The reason says why (see below).

The structured result holds the proposal’s id, status (open, accepted or rejected), duplicate, similar (IDs with a score), the inbox url, and the org.

The same feature is available to people as groundrule propose. See the Command reference.

Limits

Limit	Value
Proposals per person	30 per hour
Proposals per organization	500 per day

Over a limit, the result is Not proposed: Too many proposals. Wait a while and try again.

Troubleshooting

What you see	What to do
This repository has no Groundrule configuration, or it couldn't be loaded. Run `groundrule doctor`.	The server didn’t find .groundrule/config.yaml, or the config has errors. Check that the agent starts the server in the repository (or pass -C <repo>), and run npx @groundrule/cli doctor there.
Not proposed: This repository isn't connected to Groundrule. Run `groundrule init --org <your-org>`, or pass --org.	The config has no platform: section. Connect the repository with npx @groundrule/cli init --org acme-payments --force, or add platform: { org: acme-payments } to the config.
Not proposed: Not signed in to acme-payments on https://app.groundrule.dev. Run `groundrule login` first.	Run npx @groundrule/cli login in a terminal. The server reads the same saved login.
Not proposed: This sign-in can't propose rules yet. Run groundrule login again to refresh it.	The token lacks the propose permission. Run login again, or create a token with Propose rules.
list_standards returns the “no Groundrule configuration” message in a connected repository	Loading the rulebook failed. The exact reason, such as Not signed in to acme-payments on https://app.groundrule.dev. Run `groundrule login` (or set GROUNDRULE_TOKEN in CI)., is in the agent’s MCP log. Run npx @groundrule/cli doctor in the repository to see it in a terminal.
doctor or the MCP log says Your sign-in to acme-payments has expired or was revoked. Run `groundrule login` again.	Run login again. Tokens from login last 90 days, and an admin can revoke them in Settings → API tokens.
The agent shows the server as failed to start	Run npx -y @groundrule/cli mcp in a terminal. It should wait silently for input (press Ctrl-C to stop). If npx isn’t found, the agent can’t see Node.js: start the agent from a shell where node --version prints 22 or later.
✕ groundrule mcp needs standard input; run it from your coding agent's MCP settings.	The server was started without standard input. Start it from the agent’s MCP settings.
The agent never calls the tools	Ask it directly, for example “Check the Groundrule standards before you change this”. Some agents need the server turned on per chat or per workspace.

The server writes the protocol to standard output and its own messages to standard error, so diagnostics show up in your agent’s MCP log.

Related

• Agent instruction files
• Command reference
• Environment and files: GROUNDRULE_TOKEN, GROUNDRULE_URL and where logins are saved.