@emtai/xray-vision-mcp

XRay-Vision MCP server bridge for Claude Code. Connects via stdio to the remote XRay-Vision server, proxying all 85+ tools transparently.

Quick Start

Add to your Claude Code MCP config (.mcp.json or Claude Code settings):

{
  "xray-vision": {
    "command": "npx",
    "args": ["-y", "@emtai/xray-vision-mcp"]
  }
}

Authentication

Interactive (default)

On first use, a browser window opens for Cloudflare login (same as the XRay-Vision dashboard). The token is cached for 24 hours.

API Key (CI/headless)

Set the XRAY_API_KEY environment variable:

{
  "xray-vision": {
    "command": "npx",
    "args": ["-y", "@emtai/xray-vision-mcp"],
    "env": {
      "XRAY_API_KEY": "xray-your-key-here"
    }
  }
}

Get your API key from the XRay-Vision dashboard.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | XRAY_API_KEY | API key for headless/CI auth | - | | XRAY_SERVER_URL | Override server base URL | https://mcp.emtailabs.com | | XRAY_DEBUG | Enable debug logging (1 or true) | - |

How It Works

Claude Code  <-(stdio)->  @emtai/xray-vision-mcp  <-(HTTPS)->  mcp.emtailabs.com
                          (local process)                       (remote server)

The package acts as a transparent JSON-RPC bridge:

1. Reads MCP messages from stdin
2. Forwards via HTTP POST with authentication
3. Streams responses back to stdout
4. Handles SSE and JSON response formats

Token Cache

OAuth tokens are cached at ~/.xray-vision/auth.json with restricted file permissions (0600). Delete this file to force re-authentication.

Troubleshooting

"Server returned 401 Unauthorized"

• Your token may have expired. Delete ~/.xray-vision/auth.json and reconnect.
• If using XRAY_API_KEY, verify the key is valid in the dashboard.

Browser doesn't open

• The URL is printed to stderr. Copy it manually.
• Set XRAY_DEBUG=1 for verbose logging.

"OAuth callback timed out"

• Complete the browser login within 5 minutes.
• Ensure no firewall blocks localhost connections.

Requirements

• Node.js >= 18.0.0