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.

PyPI Python License

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

  1. Verify JSON syntax (no trailing commas)
  2. Quit Claude Desktop completely
  3. Restart Claude Desktop
  4. 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.

Project links

Data verified by PyPI on Sep 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.13.42)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for p.schwinger from gravatar.com p.schwinger Avatar for soulentheo from gravatar.com soulentheo

Credits

Author: David S. L. Van Assche

GitHub Statistics

Data verified by PyPI on Sep 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

mcp empirica calibration ai measurement epistemic

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

empirica_mcp-1.13.40.tar.gz (28.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

empirica_mcp-1.13.40-py3-none-any.whl (19.0 kB view details)

Uploaded Python 3

File details

Details for the file empirica_mcp-1.13.40.tar.gz.

File metadata

  • Download URL: empirica_mcp-1.13.40.tar.gz
  • Upload date:
  • Size: 28.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for empirica_mcp-1.13.40.tar.gz
Algorithm Hash digest
SHA256 4c8ac67edf751780cd5ad72acdf919f671c4af97b189cf8e2c8d4fa85d29c3e9
MD5 31d39c2fa46771baa8d714fd5bf7f7f9
BLAKE2b-256 8ffe3fe397c5cce1ab4265b1366158975bd02b845c68ce99c9d5d5ac22d91569

See more details on using hashes here.

Provenance

The following attestation bundles were made for empirica_mcp-1.13.40.tar.gz:

Publisher: release.yml on EmpiricaAI/empirica

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file empirica_mcp-1.13.40-py3-none-any.whl.

File metadata

  • Download URL: empirica_mcp-1.13.40-py3-none-any.whl
  • Upload date:
  • Size: 19.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for empirica_mcp-1.13.40-py3-none-any.whl
Algorithm Hash digest
SHA256 9a0e0f3b1f4a2abab43917059db2e805c956958dd4241ead28afc9db11d8d1f1
MD5 ce11f878b1c4f55adb528161e5a98fba
BLAKE2b-256 8c073fb7b98475d9685b8b8f4bf2975326256360238d2dd92fc9395db09a66a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for empirica_mcp-1.13.40-py3-none-any.whl:

Publisher: release.yml on EmpiricaAI/empirica

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.13.42

2 files

1.13.41

2 files

This release

1.13.40 This release

2 files

1.13.39

2 files

1.13.38

2 files

1.13.37

2 files

1.13.36

2 files

1.13.35

2 files

1.13.34

2 files

1.13.33

2 files

1.13.32

2 files

1.13.31

2 files

1.13.30

2 files

1.13.29

2 files

1.13.28

2 files

1.13.27

2 files

1.13.26

2 files

1.13.25

2 files

1.13.24

2 files

1.13.23

2 files

1.13.22

2 files

1.13.21

2 files

1.13.20

2 files

1.13.19

2 files

1.13.18

2 files

1.13.17

2 files

1.13.16

2 files

1.13.15

2 files

1.13.14

2 files

1.13.13

2 files

1.13.12

2 files

1.13.11

2 files

1.13.10

2 files

1.13.9

2 files

1.13.8

2 files

1.13.7

2 files

1.13.6

2 files

1.13.5

2 files

1.13.4

2 files

1.13.3

2 files

1.13.2

2 files

1.13.1

2 files

1.13.0

2 files

1.12.38

2 files

1.12.37

2 files

1.12.36

2 files

1.12.35

2 files

1.12.34

2 files

1.12.33

2 files

1.12.32

2 files

1.12.31

2 files

1.12.30

2 files

1.12.29

2 files

1.12.28

2 files

1.12.27

2 files

1.12.26

2 files

1.12.25

2 files

1.12.24

2 files

1.12.23

2 files

1.12.22

2 files

1.12.21

2 files

1.12.20

2 files

1.12.19

2 files

1.12.18

2 files

1.12.17

2 files

1.12.16

2 files

1.12.15

2 files

1.12.14

2 files

1.12.13

2 files

1.12.12

2 files

1.12.11

2 files

1.12.10

2 files

1.12.9

2 files

1.12.8

2 files

1.12.7

2 files

1.12.6

2 files

1.12.5

2 files

1.12.4

2 files

1.12.3

2 files

1.12.2

2 files

1.12.1

2 files

1.12.0

2 files

1.11.11

2 files

1.11.10

2 files

1.11.9

2 files

1.11.8

2 files

1.11.7

2 files

1.11.6

2 files

1.11.5

2 files

1.11.4

2 files

1.11.3

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.6

2 files

1.10.5

2 files

1.10.4

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10.0

2 files

1.9.11

2 files

1.9.10

2 files

1.9.9

2 files

1.9.8

2 files

1.9.7

2 files

1.9.6

2 files

1.9.5

2 files

1.9.4

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.20

2 files

1.8.19

2 files

1.8.18

2 files

1.8.17

2 files

1.8.16

2 files

1.8.15

2 files

1.8.14

2 files

1.8.13

2 files

1.8.12

2 files

1.8.11

2 files

1.8.10

2 files

1.8.9

2 files

1.8.8

2 files

1.8.7

2 files

1.8.4

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.13

2 files

1.7.12

2 files

1.7.11

2 files

1.7.10

2 files

1.7.9

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.23

2 files

1.6.22

2 files

1.6.21

2 files

1.6.20

2 files

1.6.19

2 files

1.6.18

2 files

1.6.17

2 files

1.6.16

2 files

1.6.15

2 files

1.6.14

2 files

1.6.13

2 files

1.6.12

2 files

1.6.11

2 files

1.6.10

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.2

2 files

1.4.1

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

1 file

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Pre-release

1.0.0b0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page