@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:

list-all-endpoints - Lists all API endpoints from the Iron.xyz OpenAPI specification in a concise format suitable for LLM consumption
get-api-specs - Gets detailed OpenAPI specification for a specific endpoint
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:

Variable	Description	Default	Options
`IRON_ENVIRONMENT`	Iron.xyz environment to use	`production`	`production`, `sandbox`
`IRON_API_KEY`	Iron.xyz API key for authentication	None	Your API key from Iron.xyz dashboard
`IRON_READ_ONLY_MODE`	Restrict to GET requests only	`false`	`true`, `false`
`IRON_BASE_URL`	Custom base URL for API calls	Auto-detected based on environment	Any valid URL
`IRON_OPENAPI_SPEC_URL`	Custom OpenAPI spec URL	Auto-detected based on environment	Any valid URL
`IRON_LOCAL_SPEC_PATH`	Local fallback spec file path	`./ironxyz-openapi-spec.yaml`	Any valid file path

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

Install dependencies:
```
pnpm install
```
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