Summary
If you're building an agent that needs to reason about crypto portfolios, this server bridges local holdings discovery with scoped market context. It reads positions from Coinbase or Kraken via read-only keys, then pulls tailored OHLC bars for major assets and quote snapshots for alts you actually hold. Tools include get_context_bundle for a full snapshot (market, sentiment, macro, regime), get_rebalance_plan for portfolio math, and check_allocation_band for drift checks. Runs stdio locally or connects to hosted HTTP MCP with x402 pay-per-call on Base. Privacy model is pass-through only with no persistence. Self-host the full ingest pipeline or lean on the hosted upstream for two to five cents per call.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
8 tools
get_market_contextReturn read-only fused market backdrop for crypto portfolio context: sentiment (Fear & Greed, Kalshi), macro events, FRED indicators, ETF flows, and market breadth — no portfolio holdings. Use get_context_bundle when you also need holdings, delta, or regime. freshness=cached r...3 params
Return read-only fused market backdrop for crypto portfolio context: sentiment (Fear & Greed, Kalshi), macro events, FRED indicators, ETF flows, and market breadth — no portfolio holdings. Use get_context_bundle when you also need holdings, delta, or regime. freshness=cached r...
Parameters* required
scopestringRollup scope: daily (default) or weekly.one of
daily · weeklyassetsarrayOptional asset symbols for market fields (default BTC and ETH), e.g. ['BTC', 'ETH', 'HYPE'].
freshnessstringcached: read local ingest DB only. live: run ingest first (requires ingest API keys on the host).one of
cached · liveget_context_bundleReturn the full read-only ContextBundle JSON: portfolio holdings, market, sentiment, macro, regime hints, and delta vs the prior saved snapshot. Use get_market_context for market-only; use get_context_at for a historical snapshot. Optional target_pct and band attach allocation...5 params
Return the full read-only ContextBundle JSON: portfolio holdings, market, sentiment, macro, regime hints, and delta vs the prior saved snapshot. Use get_market_context for market-only; use get_context_at for a historical snapshot. Optional target_pct and band attach allocation...
Parameters* required
bandnumberDrift band width as a fraction (e.g. 0.15 = 15% outside target).
scopestringRollup scope: daily (default) or weekly.one of
daily · weeklyassetsarrayOptional asset symbols for market fields (default BTC and ETH), e.g. ['BTC', 'ETH', 'HYPE'].
freshnessstringcached: read local ingest DB only. live: run ingest first (requires ingest API keys on the host).one of
cached · livetarget_pctobjectOptional target weights; when set, attaches allocation_analysis drift math to the response.
get_rebalance_planCompute read-only USD deltas and suggested exchange move lines to reach a BTC/ETH/CASH target split. Pure math — no exchange API calls. Requires allocation_pct, target_pct, and nav_usd. Use get_portfolio_state or get_context_bundle when you need live weights first.5 params
Compute read-only USD deltas and suggested exchange move lines to reach a BTC/ETH/CASH target split. Pure math — no exchange API calls. Requires allocation_pct, target_pct, and nav_usd. Use get_portfolio_state or get_context_bundle when you need live weights first.
Parameters* required
bandnumberDrift band width as a fraction (e.g. 0.15 = 15% outside target).
nav_usdnumberPortfolio net asset value in USD.
exchangestringSpot exchange for move wording: kraken (default) or coinbase.one of
kraken · coinbasetarget_pctobjectTarget BTC/ETH/CASH band weights; values typically sum to ~1.
allocation_pctobjectCurrent BTC/ETH/CASH band weights; values typically sum to ~1.
get_portfolio_stateFetch live read-only portfolio NAV, holdings[], and band weights from a supported spot exchange (e.g. Kraken, Coinbase) using credentials passed in this call (never stored). Requires exchange, api_key, and api_secret. Returns available=false with reason on invalid credentials...5 params
Fetch live read-only portfolio NAV, holdings[], and band weights from a supported spot exchange (e.g. Kraken, Coinbase) using credentials passed in this call (never stored). Requires exchange, api_key, and api_secret. Returns available=false with reason on invalid credentials...
Parameters* required
bandnumberDrift band width as a fraction (e.g. 0.15 = 15% outside target).
api_keystringRead-only exchange API key (Coinbase CDP key name).
exchangestringSpot exchange to query: kraken or coinbase.one of
kraken · coinbaseapi_secretstringRead-only API secret (Kraken base64 secret or Coinbase EC PEM).
target_pctobjectOptional target weights; when set, attaches allocation_analysis to the portfolio response.
check_allocation_bandCheck read-only drift: are BTC/ETH/CASH band weights outside the drift band vs target_pct? Returns rebalance_hint (within_band, consider_rebalance, etc.). Single scenario — use check_allocation_bands for multiple targets. Use get_rebalance_plan when you need USD move lines.3 params
Check read-only drift: are BTC/ETH/CASH band weights outside the drift band vs target_pct? Returns rebalance_hint (within_band, consider_rebalance, etc.). Single scenario — use check_allocation_bands for multiple targets. Use get_rebalance_plan when you need USD move lines.
Parameters* required
bandnumberDrift band width as a fraction (default 0.15 = 15%).
target_pctobjectTarget BTC/ETH/CASH band weights; values typically sum to ~1.
allocation_pctobjectCurrent BTC/ETH/CASH band weights; values typically sum to ~1.
get_context_atLoad a read-only ContextBundle snapshot from ingest history at a point in time. Use get_context_bundle for the latest snapshot; use get_context_delta to compare two timestamps. Returns unavailable when no snapshot matches as_of and match.6 params
Load a read-only ContextBundle snapshot from ingest history at a point in time. Use get_context_bundle for the latest snapshot; use get_context_delta to compare two timestamps. Returns unavailable when no snapshot matches as_of and match.
Parameters* required
bandnumberDrift band width as a fraction (e.g. 0.15 = 15% outside target).
as_ofstringISO-8601 timestamp for the snapshot to load.
matchstringexact: snapshot at as_of only. at_or_before (default): latest snapshot on or before as_of.one of
exact · at_or_beforescopestringRollup scope: daily (default) or weekly.one of
daily · weeklyassetsarrayOptional asset symbols for market fields (default BTC and ETH), e.g. ['BTC', 'ETH', 'HYPE'].
target_pctobjectOptional target weights; when set, attaches allocation_analysis drift math to the response.
get_context_deltaCompare two read-only ContextBundle snapshots and return notable_shifts between them. Requires prior_as_of; omit current_as_of to diff against the latest live bundle. Use get_context_at to load one snapshot without diffing.4 params
Compare two read-only ContextBundle snapshots and return notable_shifts between them. Requires prior_as_of; omit current_as_of to diff against the latest live bundle. Use get_context_at to load one snapshot without diffing.
Parameters* required
scopestringRollup scope: daily (default) or weekly.one of
daily · weeklyassetsarrayOptional asset symbols for market fields (default BTC and ETH), e.g. ['BTC', 'ETH', 'HYPE'].
prior_as_ofstringISO-8601 timestamp of the earlier snapshot (required).
current_as_ofstringISO-8601 timestamp of the later snapshot; omit for latest live bundle.
check_allocation_bandsEvaluate read-only allocation drift against multiple target_pct/band scenarios in one call. Each scenario requires target_pct; optional name and band (default 0.15). Use check_allocation_band for a single target.2 params
Evaluate read-only allocation drift against multiple target_pct/band scenarios in one call. Each scenario requires target_pct; optional name and band (default 0.15). Use check_allocation_band for a single target.
Parameters* required
scenariosarrayScenario objects, each with required target_pct and optional name and band (default 0.15).
allocation_pctobjectCurrent BTC/ETH/CASH band weights; values typically sum to ~1.
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.
New here? Cursor MCP setup — stdio in your editor, or self-hosting with local ingest. Organization: AllocContext on GitHub.
Privacy: nothing stored · one-time read-only · pass-through only when using live portfolio reads. See USE.md.
Quick start (Cursor, self-host)
1. Install
pip install "alloc-context[mcp]"
# From source: pip install -e ".[mcp]"
2. Config and secrets
Copy config/config.example.yaml to
config/config.yaml. Copy .env.example to .env and add
read-only exchange keys when you want portfolio ingest or macro feeds.
See self-hosting.md.
3. MCP config
Add to your Cursor mcp.json (or project .cursor/mcp.json):
{
"mcpServers": {
"alloc-context": {
"command": "alloc-context",
"args": [
"mcp",
"--config",
"/absolute/path/to/alloc-context/config/config.yaml"
],
"env": {
"ALLOC_CONTEXT_DB": "/absolute/path/to/alloc-context/state/alloccontext.db"
}
}
}
}
Use absolute paths. See cursor-mcp.example.json.
4. Refresh facts (optional)
python -m alloccontext --config config/config.yaml ingest
Run before a session or when you want fresh macro/regime data. No cron required.
5. Ask your agent
Call get_context_bundle for a full snapshot. Pure math tools
(check_allocation_band, get_rebalance_plan) work without portfolio credentials.
Full setup: cursor-mcp.md. Samples: examples.md.
Not financial advice.
MCP tools
| 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 (CEX keys or public EVM wallet address) |
get_expectation_review | Score optional local theses against context (pass-through) |
Market context is holdings-scoped: band assets (BTC/ETH) use OHLC bars; alt holdings (e.g. HYPE) use quote snapshots when cached. See context-bundle.md#market-coverage.
See mcp.md for arguments and resources.
Self-host and development
Run ingest and MCP on your machine — the primary supported path.
See self-hosting.md, local-dev.md
(./scripts/dev-up.sh), or docker-self-host.md.
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,mcp]"
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) |
Optional HTTP MCP + x402 on your host: mcp-http.md.
AllocContext is self-host only — we do not operate mcp.alloc-context.com.
Quickstart: agent-onramp.md · cursor-mcp.md.
Documentation
| Document | Purpose |
|---|---|
| docs/agent-onramp.md | ~2 min quickstart |
| docs/cursor-mcp.md | Cursor stdio MCP |
| docs/self-hosting.md | Local ingest + MCP |
| docs/deterministic-context-mcp-pattern.md | Ingest → rollup → MCP pattern |
| docs/mcp.md | MCP tools |
| docs/examples.md | Sample tool JSON (redacted) |
| docs/context-bundle.md | ContextBundle schema |
| docs/USE.md | License and use policy |
| docs/local-dev.md | Local internal MCP + dev ingest |
| docs/docker-self-host.md | Docker Compose self-host |
| docs/distribution.md | PyPI and MCP Registry |
| docs/publishing.md | Release workflow |
| docs/mcp-http.md | Optional HTTP + x402 (your host) |
| docs/user-config.md | Bridge user.yaml (legacy archive) |
Contributing
GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions. Unsolicited pull requests are not expected — see CONTRIBUTING.md.
License
MIT License. Self-host via PyPI. See docs/USE.md.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →