# bca-mcp

The canonical crypto MCP server for AI agents — **Python edition**. 3,500+ editorial articles, 200+ entity dossiers, 43 academy lessons, and live market data — accessible as MCP tools your agent can call natively.

Sibling of [`@blockchainacademics/mcp`](https://www.npmjs.com/package/@blockchainacademics/mcp) (TypeScript). Same REST API. Same attribution contract. Use whichever fits your stack.

**v0.2.0 ships 8 read-only MCP tools + the `bca` CLI** — the most-used corpus + market endpoints, plus a terminal-first way to explore them. Later versions expand toward parity with the TS sibling (99 tools). Starting narrow on the MCP surface is deliberate: tight tools, sharp descriptions, low-risk publish.

## Why

LLMs hallucinate about crypto. BCA ships ground-truth editorial content with full attribution. Plug this MCP server into Claude Desktop, LangChain, LlamaIndex, Eliza, or any MCP-compatible agent and your model queries the BCA corpus like any other tool — with `cite_url`, `as_of`, and `source_hash` on every response.

## Install

```bash
pip install bca-mcp
# or, isolated:
pipx install bca-mcp
# or, ephemeral:
uvx bca-mcp
```

## Zero-config first run (no API key needed)

`uvx bca-mcp` works out of the box. The package ships with a public demo key baked in that unlocks 10 marquee tools (`get_price`, `get_trending`, `get_fear_greed`, `get_market_overview`, `search_news`, `get_sentiment`, `get_entity`, `get_explainer`, `get_recent_stories`, `get_topic`). Shared global cap of 100 calls/day + 20/day per IP. On startup the server emits a one-time banner to stderr noting the demo mode is active.

## Configure (unlock all 99 tools)

Get a free API key at **https://brain.blockchainacademics.com/signup** (free tier: 2,000 calls/month per user; paid tiers unlock expanded rate limits and agent-backed research generation).

Set the env var before launching the server:

```bash
export BCA_API_KEY="bca_live_xxxxxxxxxxxxxxxx"
# optional: override the default https://api.blockchainacademics.com
export BCA_API_BASE="https://api.blockchainacademics.com"
# BCA_API_BASE_URL is also accepted as a legacy alias
```

> When `BCA_API_KEY` is set the demo banner is suppressed and you get the full 99-tool surface. When it's unset, every response carries `meta.tier: "demo"` and `meta.upgrade_url` so your agent can detect the demo path.

## Use from Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`).

Zero-config demo path (no API key needed):

```json
{
  "mcpServers": {
    "blockchainacademics": {
      "command": "python",
      "args": ["-m", "bca_mcp"]
    }
  }
}
```

Full 99-tool surface (add your key from brain.blockchainacademics.com/signup):

```json
{
  "mcpServers": {
    "blockchainacademics": {
      "command": "python",
      "args": ["-m", "bca_mcp"],
      "env": { "BCA_API_KEY": "bca_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

Restart Claude Desktop — the tools appear in the tool picker. If you installed via `pipx`, you can swap `"command": "bca-mcp"` with empty `args` (a console-script entry point is registered by the package).

## Use from LangChain

Ten lines via [`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):

```python
import asyncio, os, sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools

async def main():
    params = StdioServerParameters(
        command=sys.executable, args=["-m", "bca_mcp"],
        env={**os.environ, "BCA_API_KEY": os.environ["BCA_API_KEY"]},
    )
    async with stdio_client(params) as (r, w), ClientSession(r, w) as s:
        await s.initialize()
        tools = await load_mcp_tools(s)   # -> list[StructuredTool]
        print(await tools[0].ainvoke({"query": "stablecoin regulation"}))

asyncio.run(main())
```

Full worked example in [`examples/langchain_agent.py`](./examples/langchain_agent.py). Raw MCP client loop (no LangChain) in [`examples/generic_agent.py`](./examples/generic_agent.py).

## Use from Eliza

See [`examples/eliza_plugin.md`](./examples/eliza_plugin.md) for integration notes — `bca-mcp` plugs into Eliza's MCP plugin surface as a stdio-transport server.

## The `bca` CLI

`pip install bca-mcp` also registers a terminal-first CLI. It talks to the same REST API as the MCP server — handy for debugging, quick lookups, and shell pipelines.

```bash
bca login                                # store API key in ~/.bca/config.toml (chmod 600)
bca news search "bitcoin etf" -n 5       # recent articles, rich table + cite_url
bca entity ethereum                      # dossier panel
bca price BTC,ETH,SOL                    # spot + 24h change table
bca market overview -n 10                # top-N by market cap
bca indicator coverage-index bitcoin -w 30d
bca explainer what-is-a-blockchain       # rendered markdown
bca agent summarize-whitepaper --url https://ethereum.org/…
bca version                              # CLI + live API version
```

Every command accepts `--json` for unformatted output suitable for `jq` pipelines. Env vars (`BCA_API_KEY`, `BCA_API_BASE`) take precedence over `~/.bca/config.toml`.

## Tool catalog (v0.1.0 — 8 tools)

| Tool | Category | Endpoint | Tier |
|---|---|---|---|
| `search_news` | content | `GET /v1/articles/search` | Starter |
| `get_article` | content | `GET /v1/articles/{slug}` | Starter |
| `get_entity` | content | `GET /v1/entities/{slug}` | Starter |
| `list_entity_mentions` | content | `GET /v1/entities/{slug}/mentions` | Starter |
| `list_topics` | content | `GET /v1/topics` | Starter |
| `get_explainer` | content | `GET /v1/academy/{slug}` | Starter |
| `get_price` | market | `GET /v1/market/price` | Starter |
| `get_market_overview` | market | `GET /v1/market/overview` | Starter |

All v0.1 tools are **free tier** — no paid plan required to call them.

### Tool details

#### `search_news`
Required: `query` (1–512 chars). Optional: `entity`, `since` (ISO 8601), `topic`, `limit` (1–50, default 10).

#### `get_article`
Required: `slug` (1–240 chars).

#### `get_entity`
Required: **exactly one** of `slug` (e.g. `"vitalik-buterin"`) or `ticker` (e.g. `"ETH"`, case-insensitive). Aliases resolve automatically (`CZ` → `changpeng-zhao`, `Maker` → `makerdao`, `BSC` → `bnb-chain`, …).

#### `list_entity_mentions`
Required: `slug` (entity). Optional: `since` (ISO 8601), `limit` (1–200, default 20).

#### `list_topics`
No arguments.

#### `get_explainer`
Required: **exactly one** of `slug` (e.g. `"what-is-a-blockchain"`) or `topic` (keyword).

#### `get_price`
Required: `ids` (comma-separated CoinGecko IDs, e.g. `"bitcoin,ethereum"` — NOT exchange tickers). Optional: `vs` (quote currency, default `usd`).

#### `get_market_overview`
Optional: `limit` (1–100, default 20).

## Attribution contract

Every response includes a structured `attribution` block:

```json
{
  "data": { ... },
  "attribution": {
    "cite_url": "https://blockchainacademics.com/...",
    "as_of": "2026-04-19T12:34:56Z",
    "source_hash": "sha256:..."
  },
  "meta": null
}
```

**When your agent surfaces BCA content to a user, you MUST link `cite_url`.** This is the core trade: BCA gives agents ground-truth citations; agents give BCA distribution. `as_of` and `source_hash` let downstream systems detect staleness and verify content integrity. Fields are preserved as `null` (not dropped) when upstream omits them, so agents can detect missing provenance explicitly.

## Degraded-state envelopes

The BCA API sometimes returns `status=integration_pending` or `status=upstream_error` envelopes (200 HTTP) when a specific data source is temporarily unavailable. **The MCP server passes these through as successful tool responses** — your agent sees the envelope and decides how to surface it. This matches the TS sibling's behavior.

## Errors

The server never crashes the stdio process. All failures surface as MCP responses with `isError: true` and a JSON body:

```json
{ "error": { "code": "BCA_AUTH", "message": "..." } }
```

| Code | Meaning |
|---|---|
| `BCA_AUTH` | Invalid `BCA_API_KEY` (HTTP 401/403) |
| `BCA_TIER_LOCKED` | Tool not in your current tier's allowlist (HTTP 403). Demo tier sees this on 89 of the 99 tools — the error message includes the upgrade URL. |
| `BCA_RATE_LIMIT` | Rate limit exceeded (HTTP 429 — honor `Retry-After`) |
| `BCA_UPSTREAM` | BCA API returned 5xx or malformed JSON |
| `BCA_NETWORK` | Network failure or 20s timeout exceeded |
| `BCA_BAD_REQUEST` | Invalid tool arguments or 4xx response |

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -q
```

Run the server directly for debugging:

```bash
BCA_API_KEY=... python -m bca_mcp
```

## Contributing

Issues, PRs, and feature requests: https://github.com/blockchainacademics/bca-mcp-python

## License

MIT © 2026 Blockchain Academics