Empirica MCP Server

AI measurement and calibration tools via Model Context Protocol.

Exposes Empirica's tool surface to Claude Desktop, IDEs, and any MCP-compatible environment (Cursor, Gemini CLI, Codex, etc.). Track what AI knows, gate what it does, and compound learning across sessions — without needing Claude Code or Bash access.

Tool surface (70 tools as of 1.11.2) covers session lifecycle, the epistemic transaction loop, artifact logging, goals, project search, calibration, lessons, sync, entity registry, and (added 2026-06-03) the mesh primitives: practice_context (Ambassador addressbook), commit_context (temporal trail), listener_on/arm/off (listener facade), loop_* (adaptive scheduler), notify_emit (multi-backend dispatcher), mailbox_reply (atomic propose+complete), mesh_status (mesh health). Run empirica mcp-list-tools to see the live registry against your installed package.

Installation

pip install empirica-mcp

Note: The MCP server requires the full Empirica package for stateful operations:

pip install empirica  # Recommended - includes empirica-mcp

Verify Installation

empirica --version      # CLI
empirica-mcp --help     # MCP server

Quick Start

1. Standard Mode

empirica-mcp

Works as a standard MCP tool provider. No epistemic layer.

2. Epistemic Mode

export EMPIRICA_EPISTEMIC_MODE=true
empirica-mcp

Every tool call now includes epistemic self-awareness - the server maintains vector state and routes behavior based on confidence/uncertainty.

3. Personality Profiles

# Cautious (investigates early)
export EMPIRICA_PERSONALITY=cautious_researcher

# Pragmatic (action-oriented)
export EMPIRICA_PERSONALITY=pragmatic_implementer

# Balanced (default)
export EMPIRICA_PERSONALITY=balanced_architect

# Adaptive (learns over time)
export EMPIRICA_PERSONALITY=adaptive_learner

Claude Desktop Configuration

Standard Mode

{
  "mcpServers": {
    "empirica": {
      "command": "empirica-mcp"
    }
  }
}

Epistemic Mode

{
  "mcpServers": {
    "empirica-epistemic": {
      "command": "bash",
      "args": [
        "-c",
        "EMPIRICA_EPISTEMIC_MODE=true EMPIRICA_PERSONALITY=balanced_architect empirica-mcp"
      ]
    }
  }
}

After editing config, restart Claude Desktop completely.

Available Tools

The MCP server exposes 100+ Empirica CLI commands as MCP tools:

Session Management:

session_create - Create new session
session_list - List sessions
session_show - Show session details

CASCADE Workflow:

preflight_submit - Submit PREFLIGHT assessment
check_submit - Execute CHECK gate
postflight_submit - Submit POSTFLIGHT assessment

Goals & Findings:

goals_create - Create goals
goals_list - List goals
finding_log - Log findings
unknown_log - Log unknowns

And many more...

Epistemic Responses

Standard Response

{
  "ok": true,
  "session_id": "abc123",
  "message": "Session created"
}

Epistemic Response

{
  "ok": true,
  "session_id": "abc123",
  "message": "Session created",

  "epistemic_state": {
    "vectors": {
      "know": 0.60,
      "uncertainty": 0.40,
      "context": 0.70,
      "clarity": 0.85
    },
    "routing": {
      "mode": "confident_implementation",
      "confidence": 0.85,
      "reasoning": "Know=0.60 >= 0.6, Uncertainty=0.40 < 0.5"
    }
  }
}

Behavioral Modes

Mode	Trigger	Behavior
clarify	clarity < 0.6	Ask questions before proceeding
load_context	context < 0.5	Load project data first
investigate	uncertainty > 0.6	Systematic research
confident_implementation	know >= 0.7, uncertainty < 0.4	Direct action
cautious_implementation	Moderate vectors	Careful, incremental steps

Troubleshooting

"empirica CLI not found"

# Check if empirica is in PATH
which empirica

# If not, install full package
pip install empirica

"Module not found: empirica"

# Install full package (not just MCP server)
pip install empirica

Claude Desktop not connecting

Verify JSON syntax (no trailing commas)
Quit Claude Desktop completely
Restart Claude Desktop
Check logs for errors

Docker

docker pull nubaeon/empirica:1.6.6
docker run -p 3000:3000 nubaeon/empirica:1.6.6 empirica-mcp

Requirements

Python 3.11+
empirica >= 1.5.0
mcp >= 1.0.0

Documentation

License

MIT License - See Empirica repository for details.

Metadata

Release files for empirica-mcp 1.14.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for empirica-mcp 1.14.12
File	Size	Uploaded	Provenance
empirica_mcp-1.14.12.tar.gz	29.2 kB	Oct 19, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for empirica-mcp 1.14.12
File	Interpreter	ABI	Platform	Reset
empirica_mcp-1.14.12-py3-none-any.whl 19.5 kB Oct 19, 2026 With provenance	Python 3	none	any	Details

Total release size: 48.7 kB

Release files / empirica_mcp-1.14.12.tar.gz

Download URL	empirica_mcp-1.14.12.tar.gz
Size	29.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`236573c98a16d5a2827b54daabd156b9bc8e4ed431657ab259e6d30453e12413`
BLAKE2b-256 checksum How to use checksums	`233d656cae6a52a10bbe24ace7e4346780135b3f40ee336d35c3f6821bc5cb25`
Upload date	Oct 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/EmpiricaAI/empirica
Publishing commit: github.com/EmpiricaAI/empirica/tree/d59ad483d299079886e2715614e930d325f01003

Workflow

Publishing configuration: github.com/EmpiricaAI/empirica/blob/d59ad483d299079886e2715614e930d325f01003/.github/workflows/release.yml
Publishing logs: github.com/EmpiricaAI/empirica/actions/runs/39288664833/attempts/1

Artifact

Subject: empirica_mcp-1.14.12.tar.gz
SHA-256 checksum: 236573c98a16d5a2827b54daabd156b9bc8e4ed431657ab259e6d30453e12413 Verifying attestations

Release files / empirica_mcp-1.14.12-py3-none-any.whl

Download URL	empirica_mcp-1.14.12-py3-none-any.whl
Size	19.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2f4d8f89f9730b0cc9794bfa9c8d17dc161d6b12f4677dc0b85d4e555f51dc85`
BLAKE2b-256 checksum How to use checksums	`3ee49dae13a61d08e2a3abd57755e6f6b335381da3269570e2692dbce9770ac7`
Upload date	Oct 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/EmpiricaAI/empirica
Publishing commit: github.com/EmpiricaAI/empirica/tree/d59ad483d299079886e2715614e930d325f01003

Workflow

Publishing configuration: github.com/EmpiricaAI/empirica/blob/d59ad483d299079886e2715614e930d325f01003/.github/workflows/release.yml
Publishing logs: github.com/EmpiricaAI/empirica/actions/runs/39288664833/attempts/1

Artifact

Subject: empirica_mcp-1.14.12-py3-none-any.whl
SHA-256 checksum: 2f4d8f89f9730b0cc9794bfa9c8d17dc161d6b12f4677dc0b85d4e555f51dc85 Verifying attestations

Security for empirica-mcp 1.14.12

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for empirica_mcp-1.14.12.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/EmpiricaAI/empirica
Publishing commit: github.com/EmpiricaAI/empirica/tree/d59ad483d299079886e2715614e930d325f01003

Workflow

Publishing configuration: github.com/EmpiricaAI/empirica/blob/d59ad483d299079886e2715614e930d325f01003/.github/workflows/release.yml
Publishing logs: github.com/EmpiricaAI/empirica/actions/runs/39288664833/attempts/1

Artifact

Subject: empirica_mcp-1.14.12.tar.gz
SHA-256 checksum: 236573c98a16d5a2827b54daabd156b9bc8e4ed431657ab259e6d30453e12413 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.