Docs navigation

Build your first agent

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

By the end you will have:

  1. A Crypto Brain 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

Create an account

Go to blockchainacademics.com/crypto-api/signup and continue with GitHub or Google, or enter your email. No credit card.

Copy the key

Click Reveal my API key (on the dashboard after a GitHub or Google sign-in, or on the page your confirmation email opens): the key (bca_…) is shown once, in your browser. It is never emailed. Copy it. If you lose it later, rotate it from your dashboard.

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

If you see an envelope with data, attribution.citations[], and meta.status: "complete", the key is live.

2. Install the MCP server in Claude Desktop

Prime the npx cache

bash
npx -y @blockchainacademics/mcp

First run downloads the package and prints a usage banner. Ctrl+C out: Claude Desktop will invoke it on demand after this.

Open your Claude Desktop config

macOS:

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

Windows:

powershell
notepad $env:APPDATA\Claude\claude_desktop_config.json

Paste (or merge) the BCA block

claude_desktop_config.json
json
{
  "mcpServers": {
    "blockchainacademics": {
      "command": "npx",
      "args": ["-y", "@blockchainacademics/mcp"],
      "env": {
        "BCA_API_KEY": "bca_YOUR_KEY_HERE"
      }
    }
  }
}

Fully quit and relaunch Claude Desktop

Cmd+Q on macOS, fully exit the taskbar icon on Windows. A normal close-the-window won't reload the MCP config.

Confirm the tools loaded

Open a new chat. Click the hammer icon in the input bar. You should see blockchainacademics listed with 105 tools.

3. Ask your first question

Paste this into the chat:

"Use the BCA tools to summarize the top three stories about Bitcoin ETFs. Cite each story with the URL."

Claude will:

  1. Call search_news with {query: "Bitcoin ETF", limit: 3}.
  2. Receive one envelope with the three hits in data.results[] 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, newest first:

  1. BlackRock's IBIT adds 3,441 BTC (2026-10-29): worth $276.7M, moved in from Coinbase Prime over 24 hours while Bitcoin held near $80K. [source]
  2. Bitcoin ETFs log a third straight week of net inflows (2026-07-27): the streak held even as $465M left in the last days of the week. [source]
  3. SEC opens a public consultation on crypto ETFs (2026-06-30): a formal public comment period on new ETF products, crypto and prediction market funds included. [source]

Click any link. It opens the article, and a link to our own pages carries a src= tag: that is how we attribute your agent's readership back to you, and why stripping the links breaks the deal on Free and 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 105 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 one envelope whose attribution.citations[0].cite_url names the source, with a src= tag on our own pages.
  6. Claude composed the summary and surfaced the links verbatim, which satisfies the Free-tier attribution contract.

5. Iterate

Try these prompts next to exercise different tool categories:

PromptTool that fires
"What's the entity dossier on Circle?"get_entity
"Current sentiment on Solana, with social pulse?"get_sentiment, get_social_pulse
"Give me the BCA Coverage Index for Ethereum over 30 days."get_coverage_index
"List the top 10 stablecoins by TVL."list_stablecoins
"Generate a due-diligence memo on Sui." (Pro tier, async job)generate_due_diligence
"Translate this Solidity contract to Vyper." (Team tier, async job)translate_contract

6. Handle the envelope yourself (optional)

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

typescript
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<{results: Article[]}>) {
  if (resp.meta.status === "unseeded") {
    return `No data for that yet: ${resp.meta.diagnostic?.reason ?? "not available"}.`;
  }
  // partial and stale still carry usable data; meta.diagnostic says what is missing or how old it is.
  const list = (resp.data?.results ?? [])
    .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. Over MCP, data arrives as a fenced string that needs a second parse; see Parse the envelope.

7. Where next

Troubleshooting

SymptomFix
Hammer icon missing in Claude DesktopFully quit (Cmd+Q) and relaunch. Check ~/Library/Logs/Claude/mcp*.log.
BCA_TIER_LOCKED on a tool your plan includesThe server did not read your key and is on the shared demo key (the MCP log shows [bca-mcp] Running in DEMO mode). Check the env block in claude_desktop_config.json: the name is BCA_API_KEY, no trailing comma. Then fully restart.
BCA_RATE_LIMIT on a Free keyYou hit the free tier's per-second limit or its daily cap. Cache responses, or upgrade on Pricing.
HTTP 402 on a toolYour plan is below the tool's tier, and the message names the tier it needs. See Tiers & quotas.
BCA_AUTH after rotating the keyThe old key stops at once. Paste the new key into the env block and fully restart the client.
A tool answers meta.status: "unseeded"There is no real data for that call yet: meta.diagnostic.reason says why and meta.diagnostic.eta when it is expected.

Still stuck? Ask in GitHub Discussions, or open an issue for a bug. Email [email protected] about your account or billing, or about anything at all on a paid plan. Both GitHub pages are public: post your key prefix, never the full key.