OrdiscanMCP v1

An MCP Framework HTTP server implementation with Ordiscan API integration.

Features

• HTTP Stream transport on port 1337

• Stream response mode for real-time communication

• Comprehensive Ordiscan API integration (29 tools)

• TypeScript implementation with Zod schema validation

• Detailed error handling and response formatting

• Direct API connection (no proxy required)

• Bearer token authentication

• Rate limiting handled by Ordiscan API

Related MCP server: Obsidian MCP REST Server

API Connection & Authentication

Direct Connection

All tools connect directly to the Ordiscan API (api.ordiscan.com) without requiring any proxy. This ensures:

• Faster response times

• Reduced latency

• No additional configuration needed

• Direct error handling

• Automatic rate limiting by Ordiscan API

Authentication

Every tool requires authentication using a Bearer token:

• API key must be provided either:

  1. As a parameter in each tool call (apiKey parameter)

  2. Through the ORDISCAN_API_KEY environment variable

• Authentication uses Bearer token format

• All requests include the Authorization: Bearer <your-api-key> header

• Invalid or missing API keys will result in authentication errors

Setup

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Configure your MCP client:

{
  "mcpServers": {
    "ordiscanmcpv1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-deployed-server.com/mcp"  
      ]
    }
  }
}

url: (http://localhost:1337/mcp) Remote: (https://ordiscan-mcp-v1.onrender.com/mcp)

4. Start the server:

npm start

For development with hot-reload:

npm run dev

Pass in the key with a request one time, good to go.

Project Structure

ordiscanmcpv1/
├── src/
│   ├── tools/
│   │   ├── ordiscan-utils.ts
│   │   ├── ordiscan.ts            # Main Ordiscan Tool
│   │   │
│   │   ├── # Address Tools
│   │   ├── ordiscan-utxo.ts
│   │   ├── ordiscan-inscriptions.ts
│   │   ├── ordiscan-inscriptions-detail.ts
│   │   ├── ordiscan-runes-balance.ts
│   │   ├── ordiscan-brc20-balance.ts
│   │   ├── ordiscan-rare-sats.ts
│   │   │
│   │   ├── # Activity Tools
│   │   ├── ordiscan-inscriptions-activity.ts
│   │   ├── ordiscan-runes-activity.ts
│   │   ├── ordiscan-brc20-activity.ts
│   │   │
│   │   ├── # Transaction Tools
│   │   ├── ordiscan-tx-info.ts
│   │   ├── ordiscan-tx-inscriptions.ts
│   │   ├── ordiscan-tx-inscription-transfers.ts
│   │   ├── ordiscan-tx-runes.ts
│   │   │
│   │   ├── # Inscription Tools
│   │   ├── ordiscan-inscription-info.ts
│   │   ├── ordiscan-inscription-traits.ts
│   │   ├── ordiscan-inscriptions-list.ts
│   │   ├── ordiscan-inscriptions-detail.ts
│   │   │
│   │   ├── # Collection Tools
│   │   ├── ordiscan-collections-list.ts
│   │   ├── ordiscan-collection-info.ts
│   │   ├── ordiscan-collection-inscriptions.ts
│   │   │
│   │   ├── # Rune Tools
│   │   ├── ordiscan-runes-list.ts
│   │   ├── ordiscan-rune-market.ts
│   │   ├── ordiscan-rune-name-unlock.ts
│   │   │
│   │   ├── # BRC-20 Tools
│   │   ├── ordiscan-brc20-list.ts
│   │   ├── ordiscan-brc20-info.ts
│   │   │
│   │   ├── # Sat Tools
│   │   ├── ordiscan-sat-info.ts
│   │   ├── ordiscan-utxo-rare-sats.ts
│   │   └── ordiscan-utxo-sat-ranges.ts
│   │
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Parameter Handling

All tools use robust parameter handling utilities from ordiscan-utils.ts:

Flexible Number Handling

• flexibleNumber(): Accepts both string and number inputs for numeric parameters

  • Automatically converts string numbers to integers

  • Validates numeric ranges where applicable

  • Used for pagination, ordinal numbers, and block heights

Flexible Enum Handling

• flexibleEnum(): Validates string inputs against predefined values

  • Used for sort orders ('newest'/'oldest')

  • Used for type filters and other enumerated values

  • Provides clear error messages for invalid inputs

These utilities ensure consistent parameter handling across all tools while maintaining type safety and validation.

Available Tools (29 Total)

1. Main Tool

• ordiscan_main: General-purpose tool for rune information and status

2. Address Tools (6)

• UTXO Tool: Get all UTXOs owned by a Bitcoin address

• Basic and Detailed Inscription Tools: Get inscription information for an address

• Runes Balance Tool: Get rune balances for an address

• BRC-20 Balance Tool: Get BRC-20 token balances for an address

• Rare Sats Tool: Get rare sats owned by an address

3. Activity Tools (3)

• Inscriptions Activity Tool: Track inscription transfers for an address

• Runes Activity Tool: Track rune transfers for an address

• BRC-20 Activity Tool: Track BRC-20 token transfers for an address

4. Transaction Tools (4)

• Transaction Info Tool: Get detailed transaction information

• Transaction Inscriptions Tool: Get inscriptions in a transaction

• Transaction Inscription Transfers Tool: Track inscription transfers in a transaction

• Transaction Runes Tool: Track rune transfers in a transaction

5. Inscription Tools (4)

• Inscription Info Tool: Get detailed information about an inscription

• Inscription Traits Tool: Get traits for an inscription

• Inscriptions List Tool: Get a paginated list of all inscriptions

• Inscription Transfers Tool: Track transfers of an inscription

6. Collection Tools (3)

• Collections List Tool: Get a paginated list of collections

• Collection Info Tool: Get detailed information about a collection

• Collection Inscriptions Tool: Get inscriptions in a collection

7. Rune Tools (3)

• Runes List Tool: Get a list of all runes

• Rune Market Info Tool: Get market information for a rune

• Rune Name Unlock Tool: Check rune name availability

8. BRC-20 Tools (2)

• BRC-20 List Tool: Get a list of all BRC-20 tokens

• BRC-20 Token Info Tool: Get detailed information about a BRC-20 token

9. Sat Tools (3)

• Sat Info Tool: Get information about a specific sat

• UTXO Rare Sats Tool: Get rare sats in a UTXO

• UTXO Sat Ranges Tool: Get sat ranges in a UTXO

Tool Examples

Inscription Info Tool

Get detailed information about a specific inscription.

Tool Name: ordiscan_inscription_info

Parameters:

• id (string): The inscription ID (e.g. b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0)

• apiKey (string, optional): Your Ordiscan API key

Example Response:

{
  "success": true,
  "formatted": {
    "id": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0",
    "number": 123456,
    "type": "image/png",
    "timestamp": "2024-01-01 12:00:00",
    "sat": "1,234,567",
    "content_url": "https://ordinals.com/content/...",
    "collection": "example-collection",
    "owner": {
      "address": "bc1...",
      "output": "txid:vout"
    },
    "genesis": {
      "address": "bc1...",
      "output": "txid:vout"
    }
  }
}

Rune Market Tool

Get market information for a specific rune.

Tool Name: ordiscan_rune_market

Parameters:

• name (string): The unique name of the rune (without spacers)

• apiKey (string, optional): Your Ordiscan API key

Example Response:

{
  "success": true,
  "formatted": {
    "price": {
      "sats": "1,234.56",
      "usd": "$0.50"
    },
    "market_cap": {
      "btc": "12.3456",
      "usd": "$500,000"
    }
  }
}

BRC-20 Info Tool

Get detailed information about a BRC-20 token.

Tool Name: ordiscan_brc20_info

Parameters:

• tick (string): The unique tick of the token

• apiKey (string, optional): Your Ordiscan API key

Example Response:

{
  "success": true,
  "formatted": {
    "tick": "ORDI",
    "supply": {
      "max": "21,000,000",
      "minted": "15,000,000",
      "remaining": "6,000,000",
      "percent_minted": "71.43%"
    },
    "market": {
      "price_usd": "$1.23",
      "market_cap_usd": "$18,450,000",
      "fully_diluted_market_cap_usd": "$25,830,000"
    }
  }
}

Error Handling

All tools include comprehensive error handling:

• API key validation

• Network request errors

• Invalid input validation

• Rate limiting responses from Ordiscan API

• Detailed error messages

Response Formatting

Each tool provides both raw and formatted responses:

• Raw data in the data field

• Human-readable formatted data in the formatted field

• Consistent error format across all tools

• Proper number formatting and date localization

Security Recommendations

API Key Management

• Never hardcode API keys in your code

• Use environment variables for API key storage

• Rotate API keys periodically

• Use different API keys for development and production

Error Handling

The server implements secure error handling:

• No sensitive information in error messages

• Proper HTTP status codes

• Structured error responses

• Logging of errors without exposing internals

Input Validation

All tools use strict input validation:

• Zod schema validation for all parameters

• Type checking with TypeScript

• Flexible number handling for numeric inputs

• String validation for enumerated values

Rate Limiting

Rate limiting is handled by the Ordiscan API:

• No additional rate limiting needed

• API key-based rate limits

• Proper error responses for rate limit exceeded

• Automatic rate limit handling