npm package: @mubit-ai/mcp
Description: MuBit Memory MCP Server — expose MuBit memory engine as tools for AI coding agents
Author: Mubit AI
Latest version: 0.5.0

# `@mubit-ai/mcp`

MCP server for [MuBit](https://mubit.ai), exposing the current control-plane memory and MAS surfaces as tools for coding agents.

This package now routes MuBit calls through the canonical JS SDK transport layer instead of maintaining its own raw HTTP client. That keeps endpoint/auth behavior aligned with the SDK while still exposing current MuBit-only tools.

## Install

```bash
npm install -g @mubit-ai/mcp
```

Or run it directly:

```bash
npx @mubit-ai/mcp
```

## Env vars

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `MUBIT_API_KEY` | Yes | — | MuBit instance API key |
| `MUBIT_ENDPOINT` | No | `http://127.0.0.1:3000` | MuBit HTTP endpoint |
| `MUBIT_DEFAULT_SESSION_ID` | No | `default` | Default run/session for tool calls |
| `MUBIT_DEFAULT_USER_ID` | No | — | Default user scope |

## MCP setup

Claude Code:

```bash
claude mcp add mubit-memory -- npx @mubit-ai/mcp
```

Generic `mcp.json`:

```json
{
  "mcpServers": {
    "mubit-memory": {
      "command": "npx",
      "args": ["@mubit-ai/mcp"],
      "env": {
        "MUBIT_API_KEY": "mbt_...",
        "MUBIT_ENDPOINT": "http://127.0.0.1:3000",
        "MUBIT_DEFAULT_SESSION_ID": "coding-session"
      }
    }
  }
}
```

## Tool surface

Core memory tools:

- `mubit_remember`
- `mubit_recall`
- `mubit_context`
- `mubit_archive`
- `mubit_dereference`
- `mubit_reflect`
- `mubit_lessons`
- `mubit_forget`
- `mubit_status`

MAS and learning-loop tools:

- `mubit_checkpoint`
- `mubit_outcome`
- `mubit_strategies`
- `mubit_register_agent`
- `mubit_list_agents`
- `mubit_handoff`
- `mubit_feedback`

Observability tools:

- `mubit_memory_health`
- `mubit_diagnose`

## Current parameter coverage

`mubit_remember` supports current MuBit structured ingest fields:

- `intent`: `fact`, `observation`, `lesson`, `rule`, `handoff`, `feedback`, `tool_output`, `tool_input`, `trace`, `reflection`, `task_result`, `log`, `context`
- `lesson_type`, `lesson_scope`, `lesson_importance`
- `lesson_conditions`
- `source`
- `upsert_key`
- `metadata`

`mubit_recall` supports:

- `entry_types`
- `include_working_memory`
- `agent_id`
- `session_id` / `user_id`

`mubit_context` supports current context assembly controls:

- `mode`: `full`, `summary`, `sections`
- `sections`
- `entry_types`
- `max_token_budget`
- `agent_id`

`mubit_archive` and `mubit_dereference` support exact-reference reuse:

- `artifact_kind`
- `origin_agent_id`
- `source_attempt_id`
- `source_tool`
- `labels`
- `family`
- `reference_id`

## Example flows

Checkpoint + reflection:

```text
1. mubit_checkpoint
2. mubit_reflect
3. mubit_lessons
```

MAS coordination:

```text
1. mubit_register_agent
2. mubit_handoff
3. mubit_feedback
4. mubit_context (sections=["handoffs","feedback"])
```

Failure diagnosis:

```text
1. mubit_diagnose
2. mubit_memory_health
3. mubit_recall (entry_types=["lesson","rule"])
```

## Development

```bash
cd integrations/mcp
npm install
npm test
npm run lint
npm run build
```

The published runtime entrypoint is `dist/index.js`, so `dist/` must be regenerated whenever `src/` changes.

## License

Apache-2.0