Build your first BCA agent

A complete walk-through from zero to a working Claude Desktop agent that answers crypto questions with cited sources. ~5 minutes, no crypto or LLM expertise assumed.

By the end you will have:

1. A BCA API key on the Free tier.
2. @blockchainacademics/mcp running inside Claude Desktop.
3. A chat that calls search_news, handles the response envelope, and ends with a citation link the reader can click.

1. Sign up and grab a key

curl -s "https://api.blockchainacademics.com/v1/articles/search?q=bitcoin&limit=2" \
  -H "X-API-Key: $YOUR_KEY" | head -50

2. Install the MCP server in Claude Desktop

npx -y @blockchainacademics/mcp

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

notepad $env:APPDATA\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "blockchainacademics": {
      "command": "npx",
      "args": ["-y", "@blockchainacademics/mcp"],
      "env": {
        "BCA_API_KEY": "bca_live_YOUR_KEY_HERE"
      }
    }
  }
}

3. Ask your first question

Paste this into the chat:

“Use the BCA tools to summarize the top three stories about Bitcoin ETFs this week. Cite each story with the URL.”

Claude will:

1. Call search_news with {query: "Bitcoin ETF", limit: 3}.
2. Receive three envelopes — each with data.items[] and attribution.citations[0] carrying cite_url, as_of, and source_hash.
3. Compose a summary.
4. Surface the cite_url values as clickable Markdown links.

Example output:

Three Bitcoin ETF stories from this week:

1. BlackRock’s IBIT crosses $80B AUM — net inflows $450M on 2026-04-18. [source]
2. Fidelity FBTC adds 2,300 BTC — ninth consecutive week of net positive flow. [source]
3. SEC opens comment period on in-kind redemptions — April 28 deadline. [source]

Click any link. It opens the article on blockchainacademics.com with UTM params attached — which is how we attribute your agent’s readership back to you (and why stripping the links breaks the deal on Free / Starter — see Attribution).

4. Understand what just happened

Behind the scenes:

1. Claude Desktop launched npx @blockchainacademics/mcp as a stdio subprocess.
2. The MCP server advertised its 99 tools.
3. Claude picked search_news based on your question phrasing.
4. The server forwarded the call to https://api.blockchainacademics.com/v1/articles/search?q=Bitcoin+ETF&limit=3 with your BCA_API_KEY header.
5. The backend returned three envelopes, each carrying attribution.citations[0].cite_url pre-stamped with src=claude-desktop&utm_medium=mcp&utm_campaign=search_news.
6. Claude composed the summary and surfaced the links verbatim — satisfying the Free-tier attribution contract.

5. Iterate

Try these prompts next to exercise different tool categories:

6. Handle the envelope yourself (optional)

When building a custom MCP client rather than using Claude Desktop, parse the envelope like this:

type Status = "complete" | "unseeded" | "partial" | "stale";
type Citation = { cite_url: string; as_of: string | null; source_hash: string | null };
type Envelope<T> = {
  data: T | null;
  attribution: { citations: Citation[] };
  meta: {
    status: Status;
    request_id: string;
    pageInfo: { hasNextPage: boolean; hasPreviousPage: boolean; startCursor: string | null; endCursor: string | null };
    diagnostic?: { reason: string; [k: string]: unknown };
  };
};
 
function renderAnswer(resp: Envelope<{items: Article[]}>) {
  if (resp.meta.status !== "complete") {
    return "That data source isn't live yet — try again later.";
  }
  const list = (resp.data?.items ?? [])
    .map((a) => `- **${a.title}** — ${a.summary}`)
    .join("\n");
  const citation = resp.attribution.citations[0];
  const suffix = citation
    ? `\n\n_Source: ${citation.cite_url} (retrieved ${citation.as_of})_`
    : "";
  return list + suffix;
}

The attribution.citations[0] is the contract — if the server sets it, surface it.

7. Where next

• Response envelope — every field, every edge case.
• Attribution & licensing — the citation contract, in full.
• Tool reference — all 99 tools, schema + example per tool.
• REST API — the HTTP surface underneath, for server-side callers.
• LangChain quickstart — same pattern, Python.

Troubleshooting

Still stuck? Open an issue at github.com/blockchainacademics/bca-mcp or email dev@blockchainacademics.com.