AllocContext

mcp-name: io.github.AllocContext/alloc-context

Portfolio-aware crypto context for whatever you hold — discover your holdings, holdings-scoped market data, sentiment, macro, and regime; optional allocation analysis when you supply targets. Deterministic JSON over MCP with x402 pay-per-call on Base.

New here? Agent on-ramp (~2 min) — copy-paste path to your first ContextBundle. Organization: AllocContext on GitHub — overview and integration links.

Privacy: nothing stored · one-time read-only · pass-through only — your keys and portfolio never persist on our servers. See USE.md.

Quick start (Cursor)

1. Install

pip install "alloc-context[mcp,hosted]"
# From source: pip install -e ".[mcp,hosted]"

2. User config

Copy config/user.example.yaml to ~/.config/alloc-context/user.yaml. For portfolio discovery (optional): read-only CEX keys (e.g. Coinbase, Kraken) in user config, or call hosted get_portfolio_state with exchange=wallet and a public EVM address. Add an x402 payer for hosted market context. See user-config.md.

3. MCP config

Add to your Cursor mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "alloc-context": {
      "command": "alloc-context",
      "args": [
        "mcp",
        "--user-config",
        "/Users/you/.config/alloc-context/user.yaml"
      ]
    }
  }
}

Use an absolute path for --user-config. Example: cursor-mcp-bridge.example.json.

4. Ask your agent

Call get_context_bundle for a full snapshot (holdings when a portfolio source is configured, market/sentiment/macro via hosted upstream). Pure math tools (check_allocation_band, get_rebalance_plan) work without portfolio credentials.

Full setup guide: cursor-mcp.md. Sample responses: examples.md.

Not financial advice.

Hosted MCP

Agents and wallets connect directly to the hosted endpoint — see agent-integration.md. The Cursor bridge above combines local portfolio reads with this upstream for market context.

MCP tools

Market context is holdings-scoped: band assets (BTC/ETH) use OHLC bars; alt holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes assets from your portfolio (symbols only upstream). See context-bundle.md#market-coverage.

See mcp.md for arguments, pricing, and resources.

Self-host and development

Run ingest and MCP entirely on your machine — no x402 upstream required. See self-hosting.md (self_host: true in user config), local-dev.md for the native dev stack (./scripts/dev-up.sh), or ./docker/up.sh / docker-self-host.md for Docker on loopback :8000.

git clone git@github.com:AllocContext/alloc-context.git
cd alloc-context
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
cp config/config.example.yaml config/config.yaml

python -m alloccontext ingest --dry-run
python -m alloccontext rollup --scope daily --stdout
pytest

HTTP MCP + x402: mcp-http.md. CLI entry point: alloc-context (same as python -m alloccontext).

Documentation

Contributing

GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions. Unsolicited pull requests are not expected — see CONTRIBUTING.md.

License

Elastic License 2.0 — source-available, self-host friendly. See docs/USE.md for plain-language allowed uses.

Official hosted MCP: https://mcp.alloc-context.com/mcp