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:
- A Crypto Brain API key on the Free tier.
@blockchainacademics/mcprunning inside Claude Desktop.- 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.
Smoke-test it (optional but recommended)
curl -s "https://api.blockchainacademics.com/v1/articles/search?q=bitcoin&limit=2" \
-H "X-API-Key: $YOUR_KEY" | head -50If 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
npx -y @blockchainacademics/mcpFirst 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:
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.jsonWindows:
notepad $env:APPDATA\Claude\claude_desktop_config.jsonPaste (or merge) the BCA block
{
"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:
- Call
search_newswith{query: "Bitcoin ETF", limit: 3}. - Receive one envelope with the three hits in
data.results[]andattribution.citations[0]carryingcite_url,as_of, andsource_hash. - Compose a summary.
- Surface the
cite_urlvalues as clickable Markdown links.
Example output:
Three Bitcoin ETF stories, newest first:
- 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]
- 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]
- 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:
- Claude Desktop launched
npx @blockchainacademics/mcpas a stdio subprocess. - The MCP server advertised its 105 tools.
- Claude picked
search_newsbased on your question phrasing. - The server forwarded the call to
https://api.blockchainacademics.com/v1/articles/search?q=Bitcoin+ETF&limit=3with yourBCA_API_KEYheader. - The backend returned one envelope whose
attribution.citations[0].cite_urlnames the source, with asrc=tag on our own pages. - 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:
| Prompt | Tool 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:
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
- Response envelope: every field, every edge case.
- Attribution & licensing: the citation contract, in full.
- Tool reference: every tool with its arguments and an example call.
- REST API: the HTTP surface underneath, for server-side callers.
- LangChain quickstart: same pattern, Python.
Troubleshooting
| Symptom | Fix |
|---|---|
| Hammer icon missing in Claude Desktop | Fully quit (Cmd+Q) and relaunch. Check ~/Library/Logs/Claude/mcp*.log. |
BCA_TIER_LOCKED on a tool your plan includes | The 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 key | You hit the free tier's per-second limit or its daily cap. Cache responses, or upgrade on Pricing. |
HTTP 402 on a tool | Your plan is below the tool's tier, and the message names the tier it needs. See Tiers & quotas. |
BCA_AUTH after rotating the key | The 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.