RuleMesh MCP
Connect from Codex, Claude Code, Gemini CLI, Cursor, or another Streamable HTTP coding agent. Start with a read-only access check, then pull requirements, inspect your repository locally, and report file-level evidence signals.
Connect your agent
Add the RuleMesh endpoint to your client. Use OAuth for an interactive session or an API key for CI and other non-interactive work.
Streamable HTTP
Add this URL as a remote MCP server. OAuth-capable clients discover sign-in from the endpoint and open the browser flow when authentication is required.
OAuth or API key
Use OAuth for interactive sessions. Send this header when your client does not support OAuth or when you need explicit non-interactive authentication.
| URL | https://api.rulemesh.com/mcp |
| Transport | Streamable HTTP |
| Auth (OAuth) | Automatic browser login |
| Auth (API key) | X-Api-Key: rm_... |
| Protocol | MCP (JSON-RPC over HTTP) |
Prove the connection first
Start with a read-only preview. It lists the regulations your account can reach and shows the next relevant module without reading repository files, opening a scan, or writing evidence. Continue only when the preview is useful.
- Step 1
Connect RuleMesh
Add the server with OAuth or an API key.
See setup - Step 2
Preview read-only
Confirm access and see the next module. Nothing is written.
- Step 3
Run a baseline
Inspect one module and record what the agent confirms.
Choose the next job
The first three choices cover most first visits. Open the complete library when you have a Jira module, interrupted session, applicability question, or narrower audit.
Connection check
Preview RuleMesh read-only
Use the RuleMesh MCP server to confirm the connection and preview what it can help with in this repository. 1. Call list_regulations and show which regulations this account can access. 2. Choose the first accessible regulation and call get_compliance_plan. 3. Show the highest-priority module returned, its risk summary, and what the baseline would do next with pull_rules. 4. Stop after the preview and ask whether I want to run the baseline scan. Do not start a scan. Do not inspect or edit repository files. Do not submit evidence. Do not change RuleMesh or Jira state.
Illustrative baseline summary
What the next step can return
A baseline separates what the agent found from what still needs work. Evidence is agent-submitted until a human verifies the checklist.
src/auth/session.ts
Session revocation is implemented and covered by a test.
infra/storage.tf
Encryption is configured; key-rotation evidence was not found.
No file reported
A retention deletion workflow needs engineering or operational follow-up.
prompts/get, use plan_compliance, review_bundle, scan_and_report_bundle, or implement_bundle. The copy-ready prompts above work in clients that expose tools but not MCP prompts.Code stays local. Your coding agent reads the repository and evaluates the requirements. RuleMesh receives evidence descriptions and the file names where signals were found; it does not access or upload the source files.
No RuleMesh account yet?
Create a free account, connect with OAuth, and run the read-only preview against the GDPR modules available to the FREE tier. No credit card. Your source files stay with your coding agent.
Prerequisites
- check_circleRuleMesh account
Register or sign in to RuleMesh. Interactive OAuth setup does not require an API key up front.
- check_circleMCP-compatible client
Codex, Claude Code, Gemini CLI, Cursor, Windsurf, VS Code Copilot, JetBrains, or any client supporting Streamable HTTP.
- check_circleOrganization access for authenticated tools
Evidence reporting and progress tools require an authenticated identity tied to an organization. API keys must belong to that org context.
- check_circleNetwork access
Outbound HTTPS to api.rulemesh.com on port 443.
Configuration
The public setup contract is OAuth-first. API keys remain available for automation, CI, and clients that do not yet implement MCP OAuth.
Codex
Run the CLI commands for OAuth, or add the TOML block to ~/.codex/config.toml for an environment-backed API key.
CLI + OAuth login
codex mcp add rulemesh --url https://api.rulemesh.com/mcp codex mcp login rulemesh
config.toml + RULEMESH_API_KEY
[mcp_servers.rulemesh]
url = "https://api.rulemesh.com/mcp"
env_http_headers = { "X-Api-Key" = "RULEMESH_API_KEY" }Claude Code
Add RuleMesh as a remote HTTP server. Claude Code opens the OAuth flow when the server first requires authentication.
OAuth
claude mcp add --transport http rulemesh https://api.rulemesh.com/mcp
API Key
claude mcp add --transport http rulemesh https://api.rulemesh.com/mcp --header "X-Api-Key: rm_YOUR_KEY_HERE"
Gemini CLI
Add the server to ~/.gemini/settings.json. Run /mcp auth rulemesh for OAuth and /mcp list to confirm the connection.
settings.json + OAuth
{
"mcpServers": {
"rulemesh": {
"httpUrl": "https://api.rulemesh.com/mcp"
}
}
}settings.json + API Key
{
"mcpServers": {
"rulemesh": {
"httpUrl": "https://api.rulemesh.com/mcp",
"headers": {
"X-Api-Key": "rm_YOUR_KEY_HERE"
}
}
}
}Cursor
Add the server to your project or global MCP configuration, then let Cursor complete OAuth when it connects.
OAuth
{
"mcpServers": {
"rulemesh": {
"transport": "http",
"url": "https://api.rulemesh.com/mcp"
}
}
}API Key
{
"mcpServers": {
"rulemesh": {
"transport": "http",
"url": "https://api.rulemesh.com/mcp",
"headers": {
"X-Api-Key": "rm_YOUR_KEY_HERE"
}
}
}
}Windsurf
Use the serverUrl form in Windsurf MCP settings. Add the header only when you choose API-key authentication.
OAuth
{
"mcpServers": {
"rulemesh": {
"serverUrl": "https://api.rulemesh.com/mcp"
}
}
}API Key
{
"mcpServers": {
"rulemesh": {
"serverUrl": "https://api.rulemesh.com/mcp",
"headers": {
"X-Api-Key": "rm_YOUR_KEY_HERE"
}
}
}
}VS Code Copilot
Add RuleMesh to .vscode/mcp.json or the MCP settings UI with the HTTP server type.
OAuth
{
"servers": {
"rulemesh": {
"type": "http",
"url": "https://api.rulemesh.com/mcp"
}
}
}API Key
{
"servers": {
"rulemesh": {
"type": "http",
"url": "https://api.rulemesh.com/mcp",
"headers": {
"X-Api-Key": "rm_YOUR_KEY_HERE"
}
}
}
}Desktop clients
Add RuleMesh as a remote Streamable HTTP server in the client settings. Use the URL above and authenticate when the client connects.
Claude desktop
Add RuleMesh as a remote MCP server in the client settings. OAuth uses the server URL; API-key setup adds the X-Api-Key header.
JetBrains
Go to Settings > Tools > AI Assistant > MCP Servers > Add. The IDE can open a browser for OAuth, or you can provide X-Api-Key manually.
Other coding agents
Use the Streamable HTTP endpoint shown above. OAuth-capable clients discover the authorization server; other clients can send X-Api-Key.
Local Development
Local API development uses http://localhost:5000/mcp. OAuth also works on localhost, and API key setup is still supported for dev flows.
1. Add the RuleMesh URL. 2. The client receives a 401 challenge. 3. It discovers the OAuth server and opens your browser. 4. You log in. 5. The client receives tokens and reconnects.
Tokens refresh automatically. Interactive sessions stay connected for up to 30 days before a new browser login is required.
Implementation Workflow
list_regulations + start_scan
Choose a regulation marked accessible for this account, then open a fresh scan and retain its scan_session_id.
get_compliance_plan
See the prioritized module roadmap and choose the next module to work on.
pull_rules
Fetch tasks, checklists, evidence templates, search hints, and environment-driven guidance for a module.
Implement or Audit
Build the control in your codebase or inspect the existing implementation if you are running an audit flow.
submit_signals / submit_signals_batch
Record findings once per file and thread scan_session_id when you want multiple calls grouped into one scan.
get_ticket_status + get_progress + end_scan
Review evidence and human checklist progress, identify remaining high-risk work, and close the scan.
Session Lifecycle
Scan continuity is explicit. Agents should thread scan_session_id through module, evidence, ticket-status, and progress calls when those actions belong to the same scan.
start_scan opens a clean boundary, end_scan closes it, and resume_session is only a recovery tool when a smaller model loses context.
Small-Context Agents
Smaller models should call pull_rules with limit=5 and check response_meta.truncated before assuming they saw the full module.
Page 1 is risk-sorted, so HIGH-priority work is surfaced first even when an agent cannot safely load the full payload.
Core tools
| Tool | Scope | What It Does |
|---|---|---|
| list_regulations | Read-only | Discover supported regulations, license accessibility, canonical short names, and CELEX identifiers before choosing a workflow. |
| get_compliance_plan | Read-only | Prioritized module roadmap. Accepts optional scan_session_id and echoes it back. |
| pull_rules | Read/write scan context | Module tasks with compliance_checklist, search_hints, evidence_template, clarifications_needed, and response_meta. Tasks pre-sorted HIGH → MEDIUM → LOW. |
| scan_compliance | Read-only | Returns structured requirements for the agent to evaluate against the codebase. |
| submit_signals | Authenticated | Submit one evidence item. If scan_session_id is omitted, a fresh session is created. |
| submit_signals_batch | Authenticated | Submit up to 100 evidence items in one call. Best for audits or large implementation runs. |
| get_ticket_status | Authenticated | Read Jira lifecycle state, checklist progress, and evidence summary for a module. |
| get_progress | Authenticated | Cross-session status counts, remaining high-risk work, recent evidence, and recommendations. |
| start_scan / end_scan | Authenticated | Explicitly open and close a scan boundary when you need clean session control. |
| resume_session | Authenticated | Recover the most recent active scan when a smaller model drops scan_session_id. |
| get_scan_sessions | Authenticated | List prior scan sessions for reporting and scoping follow-up work. |
Guided prompts
If your client exposes prompts/get, choose a built-in prompt below. Otherwise, copy the matching plain-language prompt from the starter library; both paths use the same RuleMesh tools.
| Prompt | Purpose |
|---|---|
| implement_bundle | Build new code for a module and submit evidence. |
| scan_and_report_bundle | Audit an existing codebase for one module and report both coverage and gaps. |
| review_bundle | Read-only module review with tasks, evidence, and open gaps. |
| plan_compliance | Generate a roadmap across modules without building anything. |
Evidence Signals
What evidence reporting means in practice
Evidence signals are the durable record of what your agent implemented or observed. They are the bridge between requirement-level guidance and file-level implementation proof.
Agents should use the evidence_template returned by pull_rules, report once per file, and separate implementation code from test coverage when both are expected.
For audit-only flows, confirmed gaps are still worth recording as manual evidence with lower confidence.
1. Use the template
The task response already contains bundle_id, requirement_id, naming guidance, minimum evidence count, and hints about expected submissions.
2. Report once per file
Do not collapse implementation and test work into a single record if they live in separate files. This keeps evidence deduplicated and reviewable.
3. Batch when useful
Use submit_signals_batch for large audits or module scans so the agent can submit many file-level findings in one call.
| Evidence Type | When To Use It |
|---|---|
| code | Source files implementing a control. |
| config | Infrastructure or application configuration such as Terraform, YAML, or environment settings. |
| test | Tests validating the control. |
| documentation | Supporting operational or policy documentation. |
| manual | Human follow-up, audit findings, or confirmed gaps. |
A current task template can require multiple submissions. The hint below is the behavior agents should follow, not optional prose.
{
"bundle_id": "access-control-security",
"requirement_id": "itreq-gdpr-art-32-para-1-req-1",
"evidence_submissions": [
{
"type": "code",
"signal_suffix": "-implementation",
"example_signal": "encryption-at-rest-implementation"
},
{
"type": "test",
"signal_suffix": "-test-coverage",
"example_signal": "encryption-at-rest-test-coverage"
}
],
"min_count": 2,
"_hint": "Call submit_signals once per file you changed or created."
}Sensitivity Scaling
Data sensitivity shapes how much evidence a task expects. Higher sensitivity means more proof, not just more verbose narrative.
When onboarding has populated cloud_env, app_type, and data_sensitivity, module guidance becomes more specific and risk amplification can raise the priority of otherwise lower-risk work.
| Level | Depth | Submissions | What To Submit |
|---|---|---|---|
| basic | Minimum viable | 1 | Implementation code |
| moderate | Robust | 2 | Implementation code + test coverage |
| high | Defense in depth | 3 | Implementation code + test coverage + documentation or config |
Compliance Scanning
scan_compliance does not ask the server to read your codebase directly. The server returns structured requirements, and the agent evaluates your implementation against those requirements.
Regulation access is tier-gated: FREE keys are GDPR only; INTEL keys include GDPR and the EU AI Act. A regulation outside your plan doesn't fail at the transport level — the tool returns a normal response with an"error": "Invalid Regulation"payload naming what your plan includes.
| Parameter | Required | Description |
|---|---|---|
| regulation | Yes | Regulation short_name — GDPR or AI_ACT. AI_ACT requires an INTEL-tier key; FREE keys are GDPR only. |
| platform | No | Platform filter such as AWS or Azure. |
| bundle | No | Scope to one module. Takes the raw anchor_hash only — unlike pull_rules’s bundle_id, a slug is not resolved and returns Not Found. |
| concern | No | Filter by concern such as encryption or access-control. |
Discovery tools
These supporting tools help agents discover the legal and controls model before implementation work starts.
| Tool | Purpose |
|---|---|
| list_regulations | List supported regulations (short_name + aliases) with an accessible flag per regulation for your key’s current tier. |
| list_frameworks | List control frameworks including cloud and OWASP mappings. |
| lookup_definition | Look up legal definitions such as personal data or controller. |
Scope Interview
A deterministic, citation-grounded scoping interview that answers "what regulations apply to me?" before you start implementation work. Supported regulations: EU AI Act (32024R1689) and GDPR (32016R0679).
The user answers plain factual questions; a deterministic engine derives the legal classification with citations and confidence scores. Every verdict is informational only — citation-backed, advisory, and never a compliance guarantee. High-stakes outcomes set requiresHumanConfirmation=true.
- Deterministic engine, not LLM. The agent elicits facts; the server's
derive()engine produces every verdict. The agent cannot override or soften a classification. - Citation-grounded. Every classification and question carries a
citesIRI+ verbatim text. Usescope_retrieve_sourceto resolve it before showing a claim to the user. - Advisory, never auto-locked. Every verdict carries an advisory note. High-stakes and derogation-clearing outcomes require human confirmation.
Scope interview tools (5)
| Tool | Access | What It Does |
|---|---|---|
| scope_next_question | Read-only | Picks the next plain-language question given facts so far (territorial → actor → subject → context → exemption). Returns the question and its citesIRI. done=true when the applicable axes are resolved. |
| scope_classify | Read-only | Runs the deterministic verdict engine over known facts. Returns per-axis classifications with citations, confidence, phased dates, an advisory note, and requiresHumanConfirmation for high-stakes outcomes. The LLM must not override this verdict. |
| scope_retrieve_source | Read-only | Resolves a citesIRI from a classification or question to its verbatim regulation span. Every claim shown to the user should be paired with this source. |
| scope_query_applicable | Read-only | Takes facts, derives the profile server-side, and returns applicable IT requirements and module ids. The server runs the engine — the agent cannot supply its own classifications. |
| scope_update_profile | Authenticated write | Persists the resolved profile to your org's scope graph (idempotent per session) and saves the full interview state. Verdict is recomputed server-side. Requires authentication. |
Typical flow
EU AI Act
CELEX 32024R1689. The default regulation for all 5 tools. Covers actor role (provider / deployer / distributor / importer), subject tier (prohibited / high-risk / GPAI / limited / minimal), and phased application dates.
GDPR
CELEX 32016R0679. Pass celex="32016R0679" to any scope tool. Covers territorial scope, controller vs. processor role, and special-category / automated-decision high-stakes paths. Expected outcomes: controller ~108 obligations, processor ~25.
Troubleshooting
helpOAuth browser never opens
Your MCP client may not support OAuth yet. Reconnect using the API key method instead of the browser-login flow.
helpAuthentication required after a while
Access tokens expire after 1 hour. Clients should refresh automatically, but after 30 days you need to reconnect and complete browser login again.
helpAuthentication required on evidence or progress calls
The API key must belong to a user attached to an organization. Without org context, submit_signals, get_ticket_status, and get_progress fail.
helpNo tasks returned for a module
The module exists but the article graphs do not yet have processed member requirements. This is a data-pipeline gap, not a local configuration issue.
helpNo environment block in pull_rules
Jira onboarding has not populated cloud_env, app_type, and data_sensitivity yet. Agents should rely on clarifications_needed and ask for missing context.
helpDisconnected after a deployment
The server is stateless, but an active HTTP connection can still drop during a restart. New sessions connect normally; reconnect the MCP server in your client.