BanditDB Docs — Native Agent Use (MCP)

Native Agent Tool Use (MCP)

Give any Claude-based agent persistent decision memory via the Model Context Protocol.

Standard LLM agents are stateless — if they route a task to the wrong model and fail, they repeat the same mistake tomorrow. BanditDB's built-in MCP server gives the entire agent swarm shared persistent memory.

The MCP server ships inside the Python SDK — no separate install:

pip install banditdb-python   # provides the banditdb-mcp entry point

Add the server to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "banditdb": {
      "command": "banditdb-mcp",
      "env": {
        "BANDITDB_URL": "http://localhost:8080",
        "BANDITDB_API_KEY": "your-secret-key"
      }
    }
  }
}

The agent now has nine tools:

Tool	What it does
`create_campaign`	Create a new decision campaign. Accepts `algorithm`, `alpha`, and an optional free-form `metadata` object for attaching context (feature names, owner, version, etc.).
`list_campaigns`	List all active campaigns with arm count, alpha, and metadata.
`campaign_diagnostics`	Per-arm `theta_norm`, prediction count, reward rate, plus `selection_entropy`, `entropy_status`, `entropy_trend`, and a `suggested_action` when collapse is detected. Use when a campaign isn't learning or you suspect exploration has stopped.
`get_intuition`	Returns the recommended action and an `interaction_id` to save.
`record_outcome`	Reports the outcome and updates the shared model — `1.0` success, `0.0` failure, or anything between. Values outside `[0, 1]` are rejected.
`batch_get_intuition`	Up to 100 decisions in one round trip, each with its own campaign and context. Partial failure is per-item: one bad context does not sink the batch.
`campaign_report`	Human-readable summary of how a campaign is performing — which arm is winning and whether the gap is meaningful yet.
`archive_campaign`	Soft-delete. The campaign stops serving but its learned model is kept.
`restore_campaign`	Reverse an archive, model intact.

Every agent in a swarm shares the same BanditDB instance, so the learned model improves with every interaction across the entire fleet.

Example: What the Agent Does

A typical decision loop inside an agent session — the agent asks for an intuition, acts on it, then reports the outcome:

// 1. Agent calls get_intuition
{ "campaign_id": "model-routing", "context": [0.8, 0.2, 0.5, 0.1] }

// → BanditDB responds
{ "arm": "claude-sonnet-5", "interaction_id": "9f2c-4e1a" }

// 2. Agent routes the task to claude-sonnet-5, task succeeds

// 3. Agent calls record_outcome
{ "interaction_id": "9f2c-4e1a", "reward": 1.0 }

Bad arguments come back as a readable message, not a crash. An agent that sends a context containing NaN, or a reward of 5.0, gets told what was wrong and which value caused it — so it can correct itself on the next turn instead of dropping the tool.

The next agent that faces a similar context — in any session, on any machine pointing at the same BanditDB instance — benefits from this outcome immediately. No retraining step, no deployment.