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

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: 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 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, which satisfies 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 is not 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. 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

Still stuck? Open an issue at github.com/blockchainacademics/bca-mcp or email [email protected].