MCP Server

ForgeOS exposes 21 governance tools over the Model Context Protocol (MCP). Any MCP-compatible agent — Claude, GPT-4, Gemini, local models — can call gate-check, submit reviews, and query institutional knowledge without custom integration. Your AI provides the intelligence — ForgeOS provides the governance. Connect via MCP with your ForgeOS API key. Raw source code stays local — only project metadata (file structure, languages, dependencies) is sent to ForgeOS.

Installation

Install globally:

npm install -g @synctek/forgeos

Or use npx for zero-install (recommended):

npx -y @synctek/forgeos@latest

Configuration

The ForgeOS MCP server runs via stdio using npx. The config block is the same across editors — only the outer key differs.

{
  "mcpServers": {
    "forgeos": {
      "command": "npx",
      "args": ["-y", "@synctek/forgeos@latest"],
      "env": {
        "FORGEOS_ENGINE_URL": "https://forgeos-api.synctek.io",
        "FORGEOS_API_KEY": "fos_your_api_key_here"
      }
    }
  }
}

Note: FORGEOS_API_KEY is your ForgeOS API key. Get it from the ForgeOS dashboard after registering. The FORGEOS_ENGINE_URL and FORGEOS_API_KEY env vars are read directly by the MCP server (distinct from the X-ForgeOS-API-Key HTTP header used by direct REST calls).

• Cursor — add to .cursor/mcp.json (project root or global Cursor settings) using the "mcpServers" key as shown above
• Claude Code — add to ~/.claude/settings.json using the "mcpServers" key as shown above
• VS Code (Copilot) — add to settings.json using "mcp": { "servers": { ... } } instead of "mcpServers"

HTTP/SSE transport

For hosted agents and cloud workflows, connect directly via HTTP/SSE:

Endpoint: https://mcp.synctek.io/mcp
Header:   X-ForgeOS-API-Key: fos_your_api_key_here

No installation required — ideal for server-side agents, CI pipelines, and any environment where running a local process is not practical.

Tools reference

ForgeOS provides 21 MCP tools organized by workflow stage.

Session

forge_init

Initialize a ForgeOS governance session. Returns project state, active work, governance rules, and workflow runbook. Call this on every session start.

forge_create_project

Create a new ForgeOS project. Projects are the top-level container for initiatives, changesets, and governance workflows.

Initiative management

forge_create_initiative

Create a new initiative to track a piece of work. Returns the initiative with a generated ID.

forge_get_workflow

Get the current workflow state for an initiative. Shows which step the developer is on, what is needed next, and overall progress.

Changeset lifecycle

forge_propose_changeset

Propose a changeset for an initiative. The engine computes a risk score and determines required gates, roles, and evidence. Returns the changeset with its risk profile and gate pipeline.

forge_submit_evidence

Submit evidence (test results, scan outputs, etc.) for a changeset. Auto-populates gate evidence requirements.

Review

forge_get_profile

Fetch a reviewer persona profile for local subagent injection. If project context is provided, the profile is enriched with Shared Mind patterns. Use the returned system_prompt as the subagent’s instructions.

forge_submit_review

Submit a complete review with findings and verdict. Creates and finalizes the review in one call.

Finding severity values: pass, warning, concern, fail.

Gates

forge_check_gates

Get the gate pipeline status for a changeset. Shows which gates are passed, pending, or failed, and what is needed to advance.

forge_promote_gate

Promote a gate to passed status. Requirements (evidence and roles) must be met. Advances the pipeline to the next gate.

forge_release_check

Check if a changeset is ready to release. Returns can_release status and any remaining blockers.

Shared Mind

forge_query_mind

Search the Shared Mind for institutional knowledge. Returns patterns, anti-patterns, and lessons relevant to the context.

forge_observe

Record an observation to the Shared Mind. Use when you discover patterns, anti-patterns, or lessons during development.

Setup and discovery

forge_quickstart

Create a sandbox project and run a complete governance cycle in seconds. Perfect for first-time setup and testing. Returns the full report including project, initiative, changeset, gates, and next steps. Takes no parameters.

forge_scorecard

Check your ForgeOS setup completeness. Shows which onboarding steps are done and what to do next. Use this to verify your environment is fully configured. Takes no parameters.

forge_discover

Analyze your repository and get a recommended governance configuration based on your tech stack. Returns recommended preset, template, evidence mapping, and CI hints.

forge_get_presets

List available governance presets (Startup, Enterprise, Regulated, Mobile Release QA). Returns all presets with descriptions so you can choose the right gate template. Takes no parameters.

forge_configure_project_gates

Configure the governance gate template for a project using a preset or custom template.

preset and custom_template are mutually exclusive.

forge_recommend_gates

Get a gate recommendation for a changeset based on risk analysis. Returns risk analysis, recommended gates, minimum gates, and rationale.

forge_workflow_template

Get copy-paste workflow templates for common scenarios (bugfix, feature, hotfix, release candidate).

forge_get_context

Get comprehensive context for a changeset including SharedMind patterns, quality warnings, past regressions, and relevant lessons. Call this before submitting evidence or reviews to make informed decisions.

Typical workflow

# First time: set up your project
forge_scorecard()                                 → setup completeness check
forge_discover(languages, ci_tools, …)            → recommended preset
forge_create_project(name, description, platform) → project created
forge_configure_project_gates(project_id, preset) → gate template applied

# Each feature or fix
forge_init(project_id)                            → session context + SharedMind state
forge_create_initiative(project_id, title, …)     → initiative created
forge_propose_changeset(project_id, …)            → risk score, gate pipeline
forge_recommend_gates(project_id, cs_id)          → gate recommendation
forge_get_context(project_id, cs_id)              → SharedMind patterns + past lessons
forge_submit_evidence(project_id, cs_id, …)       → evidence attached
forge_get_profile(role="security")                → reviewer prompt (enriched by SharedMind)
forge_submit_review(project_id, cs_id, …)         → review recorded
forge_check_gates(project_id, cs_id)              → gate status
forge_promote_gate(project_id, cs_id, gate_id)    → gate advanced
forge_release_check(project_id, cs_id)            → ready to ship

Next steps

• Authentication — API key management and security
• REST API — Full HTTP endpoint reference for direct integration