How to Using Rarible Protocol MCP

This guide covers three key ways to get started with the @rarible/protocol-mcp SDK: integrating with Claude, integrating with ChatGPT, self-hosting the MCP server, and leveraging the OpenAPI specification for custom integrations.

Prerequisites

  • Node.js: Version 20 or higher.
  • Rarible API Key: Obtain from https://rarible.org/pricing.
  • Environment Setup: Set the API key as an environment variable:
    export RARIBLE_API_KEY="your-api-key-here"
  • Tools: Familiarity with TypeScript/JavaScript, terminal commands, and optionally Postman or OpenAPI Generator.

Quick Start: Claude Integration

Integrate the SDK with Claude/OpenAI to enable AI-driven interactions using the MCP server.

Installation

Install the SDK:

npm install @rarible/protocol-mcp

Or use pnpm, bun, or yarn:

pnpm add @rarible/protocol-mcp
bun add @rarible/protocol-mcp
yarn add @rarible/protocol-mcp zod

Configure Claude

  1. Update Config:
    Add the MCP server to claude_desktop_config.json:
    {
      "mcpServers": {
        "RaribleProtocolMcp": {
          "command": "npx",
          "args": [
            "-y", "--package", "@rarible/protocol-mcp",
            "--",
            "mcp", "start",
            "--api-key-auth", "your-api-key-here"
          ]
        }
      }
    }
  2. Restart Claude

Usage

  • In Claude, use queries like "Fetch NFT details for ID ETHEREUM:0x..." or "Get collection floor price."
  • Claude maps these to SDK methods (e.g., nftItems.getItemById) and returns formatted results.

Troubleshooting

  • Verify API key and Node.js version (node -v).
  • Check Claude logs for errors like UnionApiErrorBadRequest.

ChatGPT Integration

Integrate the SDK with ChatGPT using OpenAI's MCP support to enable AI-driven interactions.

Prerequisites

  • OpenAI API Key: Obtain from https://platform.openai.com/api-keys
  • MCP Server: A publicly accessible MCP server endpoint (see Self-Hosting section below)
  • Rarible API Key: Set on your MCP server

Setup

  1. Deploy MCP Server: Ensure your MCP server is running and accessible via HTTPS
  2. Configure ChatGPT: Use the OpenAI API with MCP tools configuration

Usage Example

Use the OpenAI API with MCP tools to interact with Rarible Protocol:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -d '{
    "model": "o4-mini-2025-04-16",
    "tools": [
      {
        "type": "mcp",
        "server_label": "rarible-protocol",
        "server_url": "https://your-mcp-server.com/sse",
        "require_approval": "never"
      }
    ],
    "input": "please find NFT tokens for the owner ETHEREUM:0x28e0A9154Ed24988f30B743b5F3Cf060CC4234C0"
  }'

Configuration Parameters

  • model: Use compatible OpenAI models (e.g., o4-mini-2025-04-16)
  • server_label: Identifier for your MCP server
  • server_url: Public HTTPS endpoint of your MCP server
  • require_approval: Set to "never" for automatic tool execution

Common Use Cases

  • NFT Discovery: "Find NFTs owned by address ETHEREUM:0x..."
  • Collection Analysis: "Get floor price for collection X"
  • Market Data: "Show recent sales for NFT Y"
  • Ownership Queries: "List all collections owned by address Z"

Troubleshooting

  • 401 Unauthorized: Verify your OpenAI API key
  • MCP Server Errors: Ensure your server is publicly accessible and HTTPS-enabled
  • Rate Limits: Handle OpenAI API rate limits according to your plan
  • Tool Execution: Check MCP server logs for Rarible API errors

Self-Hosting Quick Start

Run the SDK as a local or cloud-hosted MCP server for direct API access.

Installation

  1. Create Project:

    mkdir rarible-mcp-server
    cd rarible-mcp-server
    npm init -y
    npm install @rarible/protocol-mcp
  2. Start Server:

    npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --protocol sse
  3. Optional: Customize:
    Change port or add options:

    npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --port 8080 --protocol sse

Test the Server

  • Run MCP server locally
    npx -y --package @rarible/protocol-mcp -- mcp start --api-key-auth $RARIBLE_API_KEY --port 8080 --protocol sse
  • Run MCP inspector:
    npx @modelcontextprotocol/inspector
  • Connect to mcp server an run tools:

SDK Integration

  1. Install SDK:
    npm install @rarible/protocol-mcp
  2. Example Usage:
    import { RaribleProtocolMcp } from "@rarible/protocol-mcp";
    
    const sdk = new RaribleProtocolMcp({
      apiKeyAuth: process.env.RARIBLE_API_KEY || "your-api-key-here",
    });
    
    async function run() {
      const result = await sdk.nftItems.getItemById({
        itemId: "ETHEREUM:0xb66a603f4cfe17e3d27b87a8bfcad319856518b8:32292934596187112148346015918544186536963932779440027682601542850818403729410",
      });
      console.log(result);
    }
    run();

Custom HTTP Client

  • Customize requests:
    import { HTTPClient } from "@rarible/protocol-mcp/lib/http";
    
    const httpClient = new HTTPClient({ fetcher: fetch });
    httpClient.addHook("beforeRequest", (request) => {
      request.headers.set("x-custom-header", "custom-value");
      return request;
    });
    
    const sdk = new RaribleProtocolMcp({ httpClient, apiKeyAuth: "your-api-key-here" });

Troubleshooting

  • Verify API key permissions and spec version.
  • Handle rate limits (429 errors) per Rarible's documentation.

Next Steps