MCP Integration

Mind Palace treats AI agents as first-class consumers. Schemas are contracts, not suggestions.

Two Integration Modes

MCP Integration

Setup (Claude Desktop)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mind-palace": {
      "command": "palace",
      "args": ["serve", "--root", "/path/to/project"]
    }
  }
}

Setup (Cursor)

{
  "mcp.servers": {
    "mind-palace": {
      "command": "palace",
      "args": ["serve", "--root", "${workspaceFolder}"]
    }
  }
}

Available Tools

Explore Tools

Store Tools

Recall Tools

Contradiction Detection Tools

Brief Tools

Session Tools

Conversation Tools

Corridor Tools

Semantic Search Tools

Embedding Tools

Decay Tools

Context & Scope Tools

Postmortem Tools

Available Resources

Why MCP?

• Targeted queries - Search, don’t dump
• Room-aware - Results grouped by Room
• Entry point boosting - Important files surface first
• Live index - No stale context packs
• Session tracking - Monitor agent activity
• Learning capture - Store and retrieve knowledge

Context Pack Integration

For agents that can’t use MCP:

palace explore "Fix auth bug" --full
# Provide .palace/outputs/context-pack.json to agent

The context pack contains:

• Goal and scope
• Referenced files with content
• Room context
• Provenance (scan ID, timestamp)
• Relevant learnings

Agent Rules

Must Read

Must Not Touch

Scope Discipline

If scope is "diff":
  Only modify files in the diff
  Request broader scope explicitly if needed

If scope is "full":
  Still respect guardrails
  Prefer Room-scoped changes

Verification Loop

Agent proposes → Human reviews → Save → Observer checks → Fresh ✓ or Stale ✗

With Observer (VS Code)

1. Agent queries via MCP or reads context pack
2. Agent proposes changes
3. Human saves files
4. Observer runs palace check
5. HUD shows Fresh (green) or Stale (red)
6. If stale, auto-heal runs scan

Without Observer (CLI)

# After agent changes
palace check --fast
# If stale:
palace scan && palace explore "next goal" --full

Handling Staleness

When palace check fails:

Agent: "Index is stale. Please run `palace scan` or approve auto-heal."

Never proceed with stale context. Request refresh.

Change Signal

For diff-scoped work:

palace ci signal --diff HEAD~1..HEAD
palace explore "fix bug" --full --diff HEAD~1..HEAD

Agents should:

1. Check if change-signal.json exists
2. Use its file list to scope work
3. Treat deleted files as non-editable

Session Memory Integration

Track agent work with sessions:

{
  "tool": "session_start",
  "arguments": {
    "agentType": "claude-code",
    "goal": "Implement user authentication"
  }
}

During work, log activities:

{
  "tool": "session_log",
  "arguments": {
    "sessionId": "session-123",
    "kind": "file_edit",
    "target": "src/auth/login.go",
    "outcome": "success"
  }
}

Capture learnings:

{
  "tool": "store",
  "arguments": {
    "content": "This module requires null checks",
    "kind": "learning",
    "scope": "file",
    "scopePath": "src/auth/login.go",
    "confidence": 0.85
  }
}

Before editing, check for conflicts:

{
  "tool": "session_conflict",
  "arguments": {
    "path": "src/auth/login.go"
  }
}

Failure Tracking

Record failures for learning:

{
  "tool": "store_postmortem",
  "arguments": {
    "title": "Authentication bypass bug",
    "whatHappened": "JWT validation was bypassed due to missing signature check",
    "rootCause": "Signature verification was disabled in test config and deployed to production",
    "lessonsLearned": [
      "Always validate JWT signatures",
      "Separate test and production configs"
    ],
    "severity": "high",
    "affectedFiles": ["src/auth/jwt.go", "src/middleware/auth.go"]
  }
}

Scope-Aware Context

Get context for any file with scope inheritance:

{
  "tool": "context_auto_inject",
  "arguments": {
    "filePath": "src/auth/login.go",
    "maxTokens": 2000,
    "includeLearnings": true,
    "includeDecisions": true,
    "includeFailures": true
  }
}

Understand what scope applies:

{
  "tool": "scope_explain",
  "arguments": {
    "filePath": "src/auth/login.go"
  }
}

Best Practices

1. Start a session - Always begin with start_session to enable tracking
2. Log activities - Record reads, edits, and commands for file intelligence
3. Capture learnings - Store patterns and heuristics discovered during work
4. Check for conflicts - Before editing, verify no other agent is working on the file
5. End sessions properly - Call end_session when done
6. Respect guardrails - Never touch protected files
7. Honor scope - Stay within the requested scope (diff or full)