> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Introduction

> Learn about Model Context Protocol and ChainStream MCP Server

## What is MCP

**MCP (Model Context Protocol)** is an open protocol proposed by Anthropic to standardize how AI applications connect to external data sources.

<Info>
  Simply put, MCP enables AI to:

  * Discover available tools and data sources
  * Call external tools to perform operations
  * Understand returned structured data
</Info>

### Traditional vs MCP

| Method          | Flow                                                                 |
| --------------- | -------------------------------------------------------------------- |
| **Traditional** | User → Write code → Call API → Parse data → Input to AI → Get answer |
| **MCP**         | User → Natural language question → AI auto-calls tools → Get answer  |

### Core Concepts

| Concept        | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| **MCP Server** | Server providing tools and data, like ChainStream MCP Server |
| **MCP Client** | Client using tools, like Claude Desktop, Cursor              |
| **Tools**      | Functions callable by AI, like query balance, analyze wallet |
| **Resources**  | Data resources accessible by AI                              |

***

## Why MCP Matters

### AI Agents Need "Hands and Eyes"

AI large models have powerful reasoning capabilities, but they:

* ❌ Cannot directly access real-time data
* ❌ Cannot execute external operations
* ❌ Have knowledge cutoff dates

MCP solves this by enabling AI to:

* ✅ Get real-time on-chain data
* ✅ Call professional tools for analysis
* ✅ Interact with the external world

<Note>
  **Analogy**

  MCP to AI is like:

  * **Eyes** → Let AI see real-time data
  * **Hands** → Let AI execute operations
  * **Tools** → Let AI use professional capabilities
</Note>

***

## ChainStream MCP Capabilities

ChainStream MCP Server exposes blockchain data and analysis capabilities to AI applications via the MCP protocol.

**MCP Endpoint**: `https://mcp.chainstream.io/mcp`

### Capability Matrix

ChainStream MCP Server supports all REST API and WebSocket subscription features in API Reference:

<Tabs>
  <Tab title="Token API">
    | Feature             | Description                         |
    | ------------------- | ----------------------------------- |
    | Token Search        | Search tokens by name/symbol        |
    | Token Info          | Get token basic info and metadata   |
    | Token Price         | Real-time and historical prices     |
    | Token Stats         | Volume, market cap statistics       |
    | Holder Analysis     | Holder distribution and top holders |
    | Candlestick Data    | OHLCV data for various periods      |
    | Market Data         | Liquidity, trading pair info        |
    | Security Check      | Token contract security analysis    |
    | Creation Info       | Token creator and time              |
    | Mint/Burn History   | Token minting and burning records   |
    | Liquidity Snapshots | Historical liquidity data           |
  </Tab>

  <Tab title="Wallet API">
    | Feature         | Description                       |
    | --------------- | --------------------------------- |
    | Balance Query   | Wallet token balances             |
    | PnL Calculation | Profit and loss analysis          |
    | Wallet Stats    | Transaction count, activity, etc. |
    | Balance History | Balance change records            |
  </Tab>

  <Tab title="Trade API">
    | Feature          | Description                  |
    | ---------------- | ---------------------------- |
    | Trade History    | Get trade records            |
    | Trade Activities | Real-time trading activities |
    | Top Traders      | Top traders ranking          |
  </Tab>

  <Tab title="DEX API">
    | Feature           | Description               |
    | ----------------- | ------------------------- |
    | Quote Query       | Get trade quotes          |
    | Route Calculation | Optimal trading path      |
    | Swap Execution    | Build swap transactions   |
    | DEX List          | Supported DEX information |
  </Tab>

  <Tab title="Ranking API">
    | Feature       | Description                      |
    | ------------- | -------------------------------- |
    | Hot Tokens    | Ranking by time period           |
    | New Tokens    | Newly listed tokens              |
    | Final Stretch | Near graduation on Bonding Curve |
    | Migrated      | Migrated to DEX                  |
  </Tab>

  <Tab title="WebSocket">
    | Subscription    | Description                      |
    | --------------- | -------------------------------- |
    | Token Candles   | Real-time candlestick updates    |
    | Token Stats     | Real-time statistics             |
    | Token Holders   | Holder changes                   |
    | New Tokens      | New token creation notifications |
    | Wallet Balance  | Real-time balance updates        |
    | Wallet Trades   | Real-time trade notifications    |
    | Liquidity Pools | Pool balance changes             |
  </Tab>
</Tabs>

### Supported Blockchains

| Chain    | Identifier | Type | Status |
| -------- | ---------- | ---- | ------ |
| Solana   | `sol`      | L1   | ✅      |
| Ethereum | `eth`      | L1   | ✅      |
| BSC      | `bsc`      | L1   | ✅      |

<Note>
  Use lowercase chain identifiers in all MCP tool parameters: `sol`, `eth`, `bsc`.
</Note>

***

## Supported Platforms

### Claude Desktop

Officially supported MCP client with the most complete feature support.

| Feature            | Status |
| ------------------ | ------ |
| Tool Calling       | ✅      |
| Multi-turn Dialog  | ✅      |
| Streaming Response | ✅      |

```json theme={null}
// claude_desktop_config.json
{
  "mcpServers": {
    "chainstream": {
      "url": "https://mcp.chainstream.io/mcp",
      "headers": {
        "X-API-KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor IDE

Developer-friendly AI coding assistant with MCP integration.

| Feature      | Status |
| ------------ | ------ |
| Tool Calling | ✅      |
| Code Context | ✅      |

```json theme={null}
// .cursor/mcp.json
{
  "mcpServers": {
    "chainstream": {
      "url": "https://mcp.chainstream.io/mcp",
      "headers": {
        "X-API-KEY": "your-api-key"
      }
    }
  }
}
```

### Custom Agent

Any client following MCP protocol can integrate.

```javascript theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.chainstream.io/mcp'),
  {
    requestInit: {
      headers: {
        'X-API-KEY': process.env.CHAINSTREAM_API_KEY
      }
    }
  }
);

const client = new Client({
  name: 'my-agent',
  version: '1.0.0'
});

await client.connect(transport);

// List available tools
const { tools } = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: 'wallets_profile',
  arguments: {
    address: '0x...',
    chain: 'eth'
  }
});
```

***

## Typical Use Cases

### Case 1: AI Research Assistant

**Need**: Use AI to analyze a specific wallet's trading behavior

<Steps>
  <Step title="User Question">
    Analyze the trading style of address `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`
  </Step>

  <Step title="AI Calls Tool">
    Calls `wallets_profile` tool
  </Step>

  <Step title="AI Returns Analysis">
    Based on analysis, this address (Vitalik) characteristics:

    * Wallet age: Over 5 years
    * Main holdings: ETH, various ERC-20 Tokens
    * Trading style: Long-term holding, occasional donations and project support
    * Active protocols: Uniswap, ENS, Gitcoin
    * Labels: Core developer, Philanthropist
  </Step>
</Steps>

### Case 2: Smart Money Tracking

**Need**: Track Smart Money large trades

<Steps>
  <Step title="User Question">
    Which Smart Money addresses have been buying ARB in the last 24 hours?
  </Step>

  <Step title="AI Calls Tool">
    Calls `market_trending` tool
  </Step>

  <Step title="AI Returns Results">
    In the past 24 hours, the following Smart Money addresses bought ARB:

    1. `0xabc...123` (Labels: whale, defi\_expert)
       * Amount: 500,000 ARB
       * Value: \$450,000
       * Time: 2 hours ago

    2. `0xdef...456` (Labels: institution)
       * Amount: 200,000 ARB
       * Value: \$180,000
       * Time: 5 hours ago

    Overall trend: Smart Money net buying ARB
  </Step>
</Steps>

### Case 3: Token Security Analysis

**Need**: Analyze token security

<Steps>
  <Step title="User Question">
    Help me check if this token `0x...` is safe
  </Step>

  <Step title="AI Calls Tool">
    Calls `tokens_analyze` tool
  </Step>

  <Step title="AI Returns Results">
    Token security check results:

    | Check Item             | Result             |
    | ---------------------- | ------------------ |
    | Contract Verified      | ✅                  |
    | No Malicious Functions | ✅                  |
    | Liquidity Locked       | ✅                  |
    | Holder Distribution    | ⚠️ Top 10 hold 45% |
    | Trading Tax            | Buy 1% / Sell 1%   |

    Risk Level: Medium (watch holder concentration)
  </Step>
</Steps>

***

## Technical Architecture

```mermaid theme={null}
sequenceDiagram
    participant User
    participant AI as AI Client<br/>(Claude / Cursor)
    participant MCP as ChainStream MCP<br/>(17 Tools)
    participant API as ChainStream API<br/>(SOL / ETH / BSC)

    User->>AI: "Is this token safe to buy?"
    AI->>AI: Select tokens_analyze tool
    AI->>MCP: tokens_analyze(chain, address)
    MCP->>API: GET /v2/token/{chain}/{address}
    MCP->>API: GET /v2/token/{chain}/{address}/security
    MCP->>API: GET /v2/token/{chain}/{address}/topHolders
    API-->>MCP: Token data + security flags + holders
    MCP-->>AI: Structured analysis result
    AI-->>User: "This token has no honeypot risk,<br/>top 10 holders own 35%..."
```

### Connection Modes

| Mode          | Endpoint                           | Best For                                       |
| ------------- | ---------------------------------- | ---------------------------------------------- |
| **Cloud**     | `https://mcp.chainstream.io/mcp`   | Zero setup, always up-to-date                  |
| **npm stdio** | `npx @chainstream-io/mcp`          | Local IDE integration (Claude Desktop, Cursor) |
| **npm HTTP**  | `chainstream-mcp --transport http` | Team servers, cloud deployment                 |

***

## Difference from Traditional API

| Feature            | Traditional API     | MCP                        |
| ------------------ | ------------------- | -------------------------- |
| Call Method        | HTTP REST           | Protocol Standardized      |
| Target User        | Developers          | AI Models                  |
| Parameter Handling | Manual Construction | AI Auto-inference          |
| Error Handling     | Status Codes        | Semantic Errors            |
| Context            | Stateless           | Session Context Maintained |

***

## Authentication

ChainStream MCP Server authenticates via **API Key**. Get your key from the [ChainStream Dashboard](https://www.chainstream.io/dashboard) and configure it based on your transport:

| Transport               | How to Pass API Key                                                |
| ----------------------- | ------------------------------------------------------------------ |
| **npm package** (stdio) | `CHAINSTREAM_API_KEY` environment variable or `--api-key` CLI flag |
| **Cloud endpoint**      | `X-API-KEY` request header                                         |

```bash theme={null}
# Stdio: set env var
export CHAINSTREAM_API_KEY=your-key
chainstream-mcp

# Stdio: or use CLI flag
chainstream-mcp --api-key your-key
```

<Note>
  API Keys do not expire unless you set an expiration in the Dashboard. No token refresh is needed.
</Note>

***

## Security Model

<AccordionGroup>
  <Accordion title="Authentication" icon="key">
    Both connection modes authenticate via API Key. The npm package reads `CHAINSTREAM_API_KEY` from the environment. The cloud endpoint accepts the `X-API-KEY` header.
  </Accordion>

  <Accordion title="Tool Safety" icon="lock">
    Tools are categorized by risk level:

    * **Read-only tools**: Token search, wallet profile, market data — safe by default
    * **Trading tools** (`dex_swap`, `dex_create_token`, `transaction_send`): Marked as HIGH RISK, MCP clients should require explicit user confirmation
  </Accordion>

  <Accordion title="Audit Logs" icon="file-lines">
    All tool calls are fully logged and viewable in Dashboard.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="gear" href="/en/docs/ai-agents/mcp-server/setup">
    Configure MCP Server in 5 minutes
  </Card>

  <Card title="Tools Catalog" icon="wrench" href="/en/docs/ai-agents/mcp-server/tools">
    View all available tool details
  </Card>
</CardGroup>