MCP Server Setup

UnfoldAI includes a local MCP (Model Context Protocol) server that exposes your monitoring data to external AI agents. This means agents like Claude Code can check for errors, review risk signals, and search institutional memory — all programmatically.

Why Use the MCP Server?

Without MCP, your AI agents operate blind — they don't know if their previous commands caused errors or if a known solution exists. With the MCP server, agents can:

• Check for active risk signals before making more changes
• Look up known solutions (Playbooks) when they hit errors
• Review the session state to understand what happened
• Access pre-commit data to self-review their work

Setup

Step 1: Enable the MCP Server

// settings.json
{
  "unfoldai.mcp.enabled": true
}

Step 2: Start the Server

Run the command from the Command Palette:

UnfoldAI: Register MCP Server

This starts the local MCP bridge process. The server communicates via stdio and runs entirely on your machine.

Step 3: Configure Your Agent

The MCP server currently requires manual configuration in your agent's MCP client settings. The server runs as a local stdio process.

Claude Code

Add UnfoldAI to your Claude Code MCP configuration (.mcp.json in your project root or ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "unfoldai": {
      "command": "node",
      "args": ["<path-to-unfoldai-extension>/dist/mcp/mcpServer.js"],
      "env": {}
    }
  }
}

tip

The extension path varies by platform and VS Code installation. Check your VS Code extensions directory (typically ~/.vscode/extensions/taldennis-unfoldai-chatgpt-copilot.unfoldai-<version>/).

Cursor

Cursor supports MCP servers in its configuration. Add UnfoldAI using the same stdio configuration pattern:

{
  "mcpServers": {
    "unfoldai": {
      "command": "node",
      "args": ["<path-to-unfoldai-extension>/dist/mcp/mcpServer.js"]
    }
  }
}

Refer to Cursor's MCP documentation for the exact config file location.

Other MCP-Compatible Agents

Any agent that supports the Model Context Protocol can connect to UnfoldAI's MCP server using the stdio transport. Configure the agent to launch the UnfoldAI MCP server as a child process using the path above.

Available MCP Tools

The MCP server exposes 5 read-only tools:

get_active_session

Returns information about the current monitoring session.

Use case: An agent wants to understand the current workspace state before making decisions.

Returns: Session summary including active agents, recent events, duration, and health status.

get_run_report

Returns the latest pre-commit style run report.

Use case: An agent reviewing its own work before suggesting a commit.

Returns: Files changed, risk signals, command history, and session metrics.

get_risk_signals

Returns current risk indicators for the session.

Use case: A deployment script or review agent checking if it's safe to proceed.

Returns: Risk level, active warnings, unresolved episodes.

get_recent_issues

Returns recently detected issues and episodes.

Use case: An agent checking if its previous commands caused problems.

Returns: Recent episodes with error details and current status.

search_playbooks

Searches institutional memory for relevant solutions.

Input: Query string (error message, topic, keyword).

Use case: An agent looking up known solutions when it encounters an error.

Returns: Matching Playbooks with resolution steps.

Example: Agent Using UnfoldAI Data

Here's how you might instruct a custom agent to use UnfoldAI:

Before making changes to the codebase:
1. Call get_risk_signals to check current workspace health
2. If risk is elevated, call get_recent_issues to understand what's wrong
3. If you encounter an error, call search_playbooks to find known solutions
4. After making changes, call get_run_report to review your work

Security & Privacy

Property	Guarantee
Read-only	All 5 tools are queries — none can modify files, run commands, or trigger actions
Local-only	The MCP server runs on your machine via stdio — no network exposure
Workspace-scoped	Tools only return data for the currently active VS Code workspace
Opt-in	Disabled by default — you must explicitly enable unfoldai.mcp.enabled
Privacy-aware	If unfoldai.privacy.localOnly is enabled, search_playbooks returns only locally cached data

Troubleshooting

Server not starting

• Verify unfoldai.mcp.enabled is true
• Run the UnfoldAI: Register MCP Server command
• Check that the extension is activated (sidebar should be visible)

Agent can't connect

• Verify the path to mcpServer.js in your agent's config
• The extension must be active in VS Code for the MCP server to be available
• Check your agent's MCP client logs for connection errors

No data returned

• The MCP server needs an active monitoring session — open a workspace and let some agent activity occur
• Verify UnfoldAI's sidebar shows activity before querying via MCP