Production Environment

MCP Server Documentation

Connect RuleMesh to your coding agent with OAuth-first setup, use bundle-driven compliance workflows, and record evidence signals that stay useful for both engineers and AI agents.

Quick Start

rocket_launchOAuth First

Recommended for users and agents

claude mcp add rulemesh https://api.rulemesh.com/mcp

Most interactive clients only need the server URL. Your client hits the MCP endpoint, opens a browser, and handles token refresh automatically.

keyAPI Key

Best for CI, scripts, unsupported clients

claude mcp add --transport http rulemesh https://api.rulemesh.com/mcp --header "X-Api-Key: rm_YOUR_KEY_HERE"

Use API keys when your client does not support OAuth yet, or when you need explicit non-interactive automation.

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)

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
Claude Code, Claude AI, Cursor, Windsurf, VS Code Copilot, JetBrains, or any client supporting Streamable HTTP transport.
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.

terminal

Claude Code

Use the client-specific schema below. Do not reuse one tool's JSON format for another.

OAuth

claude mcp add 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"

code

Cursor

Use the client-specific schema below. Do not reuse one tool's JSON format for another.

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 client-specific schema below. Do not reuse one tool's JSON format for another.

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

Use the client-specific schema below. Do not reuse one tool's JSON format for another.

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

Claude AI

Go to Settings > MCP Servers > Add Server. OAuth uses only the URL. API key setup uses the same URL plus 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.

Custom Clients

Any MCP client supporting Streamable HTTP can connect. OAuth discovery happens through the .well-known authorization-server endpoint.

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

get_compliance_plan→get_bundle_tasks→implement / audit→report_evidence→scan_compliance→get_ticket_status→get_progress

chatExample Conversation

You: "What's my GDPR compliance plan?"

Agent: [calls get_compliance_plan] → shows bundle roadmap

You: "Start with the encryption bundle."

Agent: [calls get_bundle_tasks] → gets tasks, checklist, search_hints, evidence_template

Agent: [implements or audits code, reports evidence once per file]

Agent: [calls scan_compliance and get_ticket_status] → verifies gaps and checklist progress

You: "What's my progress now?"

Agent: [calls get_progress] → shows overall score, remaining risk, recent evidence

get_compliance_plan

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

get_bundle_tasks

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

Implement or Audit

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

report_evidence / report_evidence_batch

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

scan_compliance + get_ticket_status

Re-scan the bundle, verify checklist progress, and close the evidence feedback loop with Jira-backed status.

get_progress

Review overall status, remaining high-risk work, recent evidence, and the next recommended bundle.

Session Lifecycle

Scan continuity is explicit. Agents should thread scan_session_id through bundle, 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 get_bundle_tasks with limit=5 and check response_meta.truncated before assuming they saw the full bundle.

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
get_compliance_plan	Read-only	Prioritized bundle roadmap. Accepts optional scan_session_id and echoes it back.
get_bundle_tasks	Read/write scan context	Bundle tasks with compliance_checklist, search_hints, evidence_template, clarifications_needed, and response_meta.
scan_compliance	Read-only	Returns structured requirements for the agent to evaluate against the codebase.
report_evidence	Authenticated	Submit one evidence item. If scan_session_id is omitted, a fresh session is created.
report_evidence_batch	Authenticated	Submit many 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 bundle.
get_progress	Authenticated	Cross-session dashboard for overall score, bundle status, 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

MCP prompts orchestrate multi-tool workflows. They require client support for prompts/get. Claude Code supports this; some other clients still require direct tool calls.

Prompt	Purpose
implement_bundle	Build new code for a bundle and submit evidence.
scan_and_report_bundle	Audit an existing codebase for one bundle and report both coverage and gaps.
review_bundle	Read-only bundle review with tasks, evidence, and open gaps.
plan_compliance	Generate a roadmap across bundles 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 get_bundle_tasks, 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 anchor_hash, 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 report_evidence_batch for large audits or bundle 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.

codeEvidence Template Example

A current task template can require multiple submissions. The hint below is the behavior agents should follow, not optional prose.

{
  "anchor_hash": "abc123",
  "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 report_evidence 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, bundle guidance becomes more specific and risk amplification can raise the priority of otherwise lower-risk work.

Basic

Implementation only

Moderate

Code + tests

High

Defense in depth

layers

Environment-Aware

Evidence Depth

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

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.

ruleStructured Requirements

searchAgent-Led Evaluation

topicConcern and Layer Filters

fact_checkGap Reporting

Parameter	Required	Description
regulation	Yes	Regulation name, currently GDPR.
platform	No	Platform filter such as AWS or Azure.
bundle	No	Scope to one bundle by anchor_hash.
concern	No	Filter by concern such as encryption or access-control.
layer	No	Scope evaluation to frontend, backend, or infrastructure.

Discovery tools

These supporting tools help agents discover the legal and controls model before implementation work starts.

Tool	Purpose
list_regulations	List supported regulations and access tiers.
list_frameworks	List control frameworks including cloud and OWASP mappings.
lookup_definition	Look up legal definitions such as personal data or controller.

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, report_evidence, get_ticket_status, and get_progress fail.

helpNo tasks returned for a bundle

The bundle 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 get_bundle_tasks

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.

← Back to documentation