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.

rocket_launchServer endpoint

Streamable HTTP

https://api.rulemesh.com/mcp

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.

keyAuthentication

OAuth or API key

X-Api-Key: rm_YOUR_KEY_HERE

Use OAuth for interactive sessions. Send this header when your client does not support OAuth or when you need explicit non-interactive authentication.

URLhttps://api.rulemesh.com/mcp
TransportStreamable HTTP
Auth (OAuth)Automatic browser login
Auth (API key)X-Api-Key: rm_...
ProtocolMCP (JSON-RPC over HTTP)
Your first run

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.

  1. Step 1

    Connect RuleMesh

    Add the server with OAuth or an API key.

    See setup
  2. Step 2

    Preview read-only

    Confirm access and see the next module. Nothing is written.

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

Confirmed signal

src/auth/session.ts

Session revocation is implemented and covered by a test.

Partial signal

infra/storage.tf

Encryption is configured; key-rotation evidence was not found.

Gap

No file reported

A retention deletion workflow needs engineering or operational follow-up.

Built-in MCP prompts: If your client supports 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.

Create a free account

Prerequisites

  • check_circle
    RuleMesh account

    Register or sign in to RuleMesh. Interactive OAuth setup does not require an API key up front.

  • check_circle
    MCP-compatible client

    Codex, Claude Code, Gemini CLI, Cursor, Windsurf, VS Code Copilot, JetBrains, or any client supporting Streamable HTTP.

  • check_circle
    Organization 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_circle
    Network 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.

smart_toy

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" }
terminal

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"
auto_awesome

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"
      }
    }
  }
}
code

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"
      }
    }
  }
}
air

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"
      }
    }
  }
}
integration_instructions

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.

travel_exploreWhat Happens During OAuth

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_regulationsstart_scanget_compliance_planpull_rulesimplement / auditsubmit_signalsget_ticket_statusget_progressend_scan
chatExample Conversation
You: "Start a scan for a regulation this account can access."
Agent: [calls list_regulations, start_scan, get_compliance_plan] → shows accessible regulations and module roadmap
You: "Start with the encryption module."
Agent: [calls pull_rules] → gets tasks, checklist, search_hints, evidence_template
Agent: [implements or audits code, reports evidence once per file]
Agent: [calls get_ticket_status] → shows evidence and human checklist progress
You: "What's my progress now?"
Agent: [calls get_progress] → shows status counts, remaining risk, recent evidence
1

list_regulations + start_scan

Choose a regulation marked accessible for this account, then open a fresh scan and retain its scan_session_id.

2

get_compliance_plan

See the prioritized module roadmap and choose the next module to work on.

3

pull_rules

Fetch tasks, checklists, evidence templates, search hints, and environment-driven guidance for a module.

4

Implement or Audit

Build the control in your codebase or inspect the existing implementation if you are running an audit flow.

5

submit_signals / submit_signals_batch

Record findings once per file and thread scan_session_id when you want multiple calls grouped into one scan.

6

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

ToolScopeWhat It Does
list_regulationsRead-onlyDiscover supported regulations, license accessibility, canonical short names, and CELEX identifiers before choosing a workflow.
get_compliance_planRead-onlyPrioritized module roadmap. Accepts optional scan_session_id and echoes it back.
pull_rulesRead/write scan contextModule tasks with compliance_checklist, search_hints, evidence_template, clarifications_needed, and response_meta. Tasks pre-sorted HIGH → MEDIUM → LOW.
scan_complianceRead-onlyReturns structured requirements for the agent to evaluate against the codebase.
submit_signalsAuthenticatedSubmit one evidence item. If scan_session_id is omitted, a fresh session is created.
submit_signals_batchAuthenticatedSubmit up to 100 evidence items in one call. Best for audits or large implementation runs.
get_ticket_statusAuthenticatedRead Jira lifecycle state, checklist progress, and evidence summary for a module.
get_progressAuthenticatedCross-session status counts, remaining high-risk work, recent evidence, and recommendations.
start_scan / end_scanAuthenticatedExplicitly open and close a scan boundary when you need clean session control.
resume_sessionAuthenticatedRecover the most recent active scan when a smaller model drops scan_session_id.
get_scan_sessionsAuthenticatedList 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.

PromptPurpose
implement_bundleBuild new code for a module and submit evidence.
scan_and_report_bundleAudit an existing codebase for one module and report both coverage and gaps.
review_bundleRead-only module review with tasks, evidence, and open gaps.
plan_complianceGenerate 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 TypeWhen To Use It
codeSource files implementing a control.
configInfrastructure or application configuration such as Terraform, YAML, or environment settings.
testTests validating the control.
documentationSupporting operational or policy documentation.
manualHuman follow-up, audit findings, or confirmed gaps.
codeEvidence Template Example

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.

1
Basic
Implementation only
2
Moderate
Code + tests
3
High
Defense in depth
layers
Environment-Aware
Evidence Depth
LevelDepthSubmissionsWhat To Submit
basicMinimum viable1Implementation code
moderateRobust2Implementation code + test coverage
highDefense in depth3Implementation code + test coverage + documentation or config

Compliance Scanning

shield_lock

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.

ruleStructured Requirements
searchAgent-Led Evaluation
topicConcern and Platform Filters
fact_checkGap Reporting
ParameterRequiredDescription
regulationYesRegulation short_name — GDPR or AI_ACT. AI_ACT requires an INTEL-tier key; FREE keys are GDPR only.
platformNoPlatform filter such as AWS or Azure.
bundleNoScope to one module. Takes the raw anchor_hash only — unlike pull_rules’s bundle_id, a slug is not resolved and returns Not Found.
concernNoFilter 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.

ToolPurpose
list_regulationsList supported regulations (short_name + aliases) with an accessible flag per regulation for your key’s current tier.
list_frameworksList control frameworks including cloud and OWASP mappings.
lookup_definitionLook 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.

ruleDesign Invariants
  • 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. Use scope_retrieve_source to 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)

ToolAccessWhat It Does
scope_next_questionRead-onlyPicks 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_classifyRead-onlyRuns 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_sourceRead-onlyResolves 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_applicableRead-onlyTakes 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_profileAuthenticated writePersists 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

scope_next_question(loop until done)scope_classifyscope_retrieve_sourcescope_query_applicablescope_update_profile

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.