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.
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. Add read-only exchange keys for portfolio
discovery (optional) and 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 keys are set,
market/sentiment/macro via hosted upstream). Pure math tools
(check_allocation_band, get_rebalance_plan) work without exchange keys.
Full setup guide: cursor-mcp.md. Sample responses: examples.md.
Not financial advice.
| URL | https://mcp.alloc-context.com/mcp |
| Discovery | llms.txt, x402 manifest |
| Pricing | $0.02 cached context/math · $0.05 live ingest or portfolio |
| Payment | x402 on Base — USDC or EURC |
| Market scope | Tailored to your holdings (band OHLC for BTC/ETH; alt quote snapshots); bridge auto-scopes from portfolio |
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.
| Tool | Purpose |
|---|---|
get_context_bundle |
Full ContextBundle — holdings, market, sentiment, macro, delta, regime; optional allocation_analysis |
get_market_context |
Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
get_context_at |
Saved snapshot from ingest history at a given as_of |
get_context_delta |
Notable shifts between two saved snapshots |
get_rebalance_plan |
USD rebalance moves from allocation, target, and NAV |
check_allocation_band |
Drift vs target and whether allocation is outside the band |
check_allocation_bands |
Batch band checks for multiple target scenarios |
get_portfolio_state |
Live NAV and holdings (e.g. Coinbase, Kraken read-only keys) |
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.
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| Command | Purpose |
|---|---|
python -m alloccontext ingest |
Pull configured sources → SQLite |
python -m alloccontext rollup --scope daily --stdout |
ContextBundle JSON (facts) |
python -m alloccontext status |
Per-source ingest ages, snapshots, MCP /health |
alloc-context mcp |
MCP server (stdio or HTTP) |
HTTP MCP + x402: mcp-http.md. CLI entry point:
alloc-context (same as python -m alloccontext).
| Document | Purpose |
|---|---|
| docs/agent-onramp.md | Start here — ~2 min to first ContextBundle |
| docs/deterministic-context-mcp-pattern.md | Reusable ingest → rollup → MCP → x402 pattern |
| docs/langchain-integration.md | LangChain tools for hosted MCP (x402) |
| docs/docker-self-host.md | Docker Compose self-host evaluation |
| docs/cursor-mcp.md | Cursor stdio MCP (bridge default) |
| docs/user-config.md | Bridge user.yaml reference |
| docs/mcp.md | MCP tools and x402 |
| docs/agent-integration.md | Paid HTTP MCP + Bazaar for agents |
| docs/examples.md | Sample tool JSON (redacted) |
| docs/context-bundle.md | ContextBundle schema |
| docs/USE.md | Self-host vs hosted MCP (plain language) |
| docs/mcp-http.md | HTTP MCP + x402 setup |
| docs/mcp-discovery.md | Bazaar and agent discovery |
| docs/self-hosting.md | Optional Linux/systemd ingest + MCP |
| docs/local-dev.md | Local internal MCP + dev ingest |
| docs/architecture.md | Pipeline and trust boundaries |
| docs/data-sources.md | Ingest sources |
| docs/distribution.md | GitHub, PyPI, MCP Registry, directories |
| docs/publishing.md | Release workflow and version bumps |
| docs/security-ci.md | CI coverage, Bandit, and pip-audit gates |
GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions. Unsolicited pull requests are not expected — see CONTRIBUTING.md.
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