@ironxyz/mcp-server

Official MCP (Model Context Protocol) server for Iron.xyz API, designed to work with Claude Desktop, Cursor IDE and other MCP compatible clients.

Features

This MCP server provides three main tools for exploring and interacting with the Iron.xyz API:

1. list-all-endpoints - Lists all API endpoints from the Iron.xyz OpenAPI specification in a concise format suitable for LLM consumption

2. get-api-specs - Gets detailed OpenAPI specification for a specific endpoint

3. invoke-api-endpoint - Actually calls the Iron.xyz API endpoints with proper authentication and validation

Quick Start

No installation required! Use with npx in your host:

Configuration

Add this to your MCP Host (Claude Desktop / Cursor IDE etc) configuration:

{
  "mcpServers": {
    "ironxyz": {
      "command": "npx",
      "args": ["-y", "@ironxyz/mcp-server"],
      "env": {
        "IRON_ENVIRONMENT": "production"
      }
    }
  }
}

Configuration Options

Configure the server using environment variables:

Environment Examples

Production Environment (default):

{
  "env": {
    "IRON_ENVIRONMENT": "production"
  }
}

Sandbox Environment:

{
  "env": {
    "IRON_ENVIRONMENT": "sandbox"
  }
}

With API Key (for endpoint invocation):

{
  "env": {
    "IRON_ENVIRONMENT": "production",
    "IRON_API_KEY": "your-iron-api-key-here"
  }
}

Read-only mode (GET requests only):

{
  "env": {
    "IRON_ENVIRONMENT": "production",
    "IRON_API_KEY": "your-iron-api-key-here",
    "IRON_READ_ONLY_MODE": "true"
  }
}

Custom OpenAPI Spec URL:

{
  "env": {
    "IRON_ENVIRONMENT": "production",
    "IRON_OPENAPI_SPEC_URL": "https://your-custom-spec-url.com/spec"
  }
}

Development

Local Installation

1. Install dependencies:

   pnpm install

2. Build the project:

   pnpm run build

Running Locally

pnpm start

Or for development:

pnpm run dev

Tools Available

list-all-endpoints

Lists all API endpoints from the Iron.xyz OpenAPI specification.

Parameters:

• filterByTag (string, optional): Filter endpoints by tag

Example usage:

{
  "tool": "list-all-endpoints",
  "arguments": {
    "filterByTag": "users"
  }
}

get-api-specs

Gets detailed OpenAPI specification for a specific endpoint.

Parameters:

• path (string, required): The API path (e.g., '/v1/users')

• method (string, required): The HTTP method (GET, POST, PUT, DELETE, etc.)

Example usage:

{
  "tool": "get-api-specs",
  "arguments": {
    "path": "/v1/users",
    "method": "GET"
  }
}

invoke-api-endpoint

Actually calls the Iron.xyz API endpoints with proper authentication and validation.

Parameters:

• path (string, required): The API path (e.g., '/customers') - /api prefix is added automatically

• method (string, required): The HTTP method (GET, POST, PUT, DELETE, etc.)

• parameters (object, optional): Query parameters as key-value pairs

• headers (object, optional): Additional headers as key-value pairs

• body (object, optional): Request body for POST/PUT/PATCH requests

Features:

• ✅ Authentication: Automatically adds API key if configured

• ✅ Read-only mode: Optional restriction to GET requests only

• ✅ Validation: Validates endpoints against OpenAPI specification

• ✅ Error handling: Comprehensive error responses with details

• ✅ Environment awareness: Works with both sandbox and production

Example usage:

{
  "tool": "invoke-api-endpoint",
  "arguments": {
    "path": "/customers",
    "method": "GET",
    "parameters": {
      "limit": 10,
      "offset": 0
    }
  }
}

Example with POST request:

{
  "tool": "invoke-api-endpoint",
  "arguments": {
    "path": "/customers",
    "method": "POST",
    "headers": {
      "IDEMPOTENCY-KEY": "123e4567-e89b-12d3-a456-426614174000"
    },
    "body": {
      "name": "John Doe",
      "email": "john@example.com",
      "type": "individual"
    }
  }
}

Error Handling

The server includes comprehensive error handling for:

• Missing or invalid OpenAPI specification API

• Invalid endpoint paths or methods

• Network issues with external services

• Malformed tool arguments