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

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:

2. Build the project:

3. Configure your MCP client:

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

4. Start the server:

For development with hot-reload:

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

Project Structure

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:

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:

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:

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