Input: any PDF or image up to 50 MB (PDF, PNG, JPEG, GIF, WebP).

Output:

{
  "document_id": "abc-123",
  "suggested_filename": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
  "metadata": {
    "document_type": "invoice",
    "vendor": "Acme Corp",
    "date": "2026-02-15",
    "amount": 7200,
    "currency": "ILS",
    "document_number": "12345",
    "title": "Invoice",
    "tags": ["vendor", "invoice"]
  },
  "filename_patterns": {
    "date_first": "2026-02-15_Invoice_12345.pdf",
    "type_first": "Invoice_12345_2026-02-15.pdf",
    "vendor_first": "Acme-Corp_Invoice_2026-02-15.pdf",
    "date_vendor": "2026-02-15_Acme-Corp.pdf",
    "vendor_date": "Acme-Corp_2026-02-15.pdf",
    "compact": "Acme-Corp_Invoice.pdf"
  },
  "enriched_file_url": "https://api.gemina.co/files/tmp_abc123.pdf",
  "enriched_file_expires_at": "2026-02-15T12:15:00Z"
}

Three uses out of one response — pick the one your code needs, ignore the rest.

Claude Desktop's Custom Connectors UI (Customize → Connectors) only supports OAuth and doesn't accept custom headers — it can't authenticate against Gemina's X-API-Key. Use the mcp-remote stdio bridge instead.

Prerequisites

1. Node.js 18+ — install from nodejs.org (Windows: ensure "Add to PATH" stays checked; macOS/Linux: standard installer).

2. Claude Desktop capabilities — open Settings → Capabilities and turn on:

   • Code execution and file creation
   • Allow network egress
   • Domain allowlist: All domains (or add storage.googleapis.com to the narrow allowlist — that's where signed enriched-file URLs are hosted).

   Without network egress, tag_file/tag_url return JSON correctly but Claude can't fetch the enriched-file URL from storage and you'll see "Host not in allowlist". Settings only apply to new chats — start a fresh conversation after toggling.

Config

In Claude Desktop, Settings → Developer → Edit Config opens claude_desktop_config.json at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge the mcpServers block alongside any existing config:

{
  "mcpServers": {
    "gemina": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.gemina.co/api/v1/mcp/",
        "--header",
        "X-API-Key:${GEMINA_API_KEY}"
      ],
      "env": {
        "GEMINA_API_KEY": "<paste-your-key-here>"
      }
    }
  }
}

Save → fully quit Claude Desktop (Cmd+Q / right-click tray → Quit) → relaunch. First launch may take 10–30s while npx downloads mcp-remote.

Notes

• No space after X-API-Key: in the --header arg — it's the documented workaround for npx's shell-split parsing.
• The env-var indirection (${GEMINA_API_KEY}) keeps the literal key out of args, where it could leak via process listings.
• Windows + spawn npx ENOENT: Claude Desktop doesn't inherit your shell's PATH. Replace "command": "npx" with the absolute path from where npx in PowerShell (forward slashes work in JSON), e.g. "C:/Program Files/nodejs/npx.cmd".

File: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \
  --header "X-API-Key: <paste-your-key-here>"

File: .vscode/mcp.json (per workspace).

{
  "servers": {
    "gemina": {
      "type": "http",
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

In Cline's MCP settings (gear icon → MCP Servers → Edit Config), add:

{
  "mcpServers": {
    "gemina": {
      "type": "streamableHttp",
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

File: ~/.codeium/windsurf/mcp_config.json. Note: the field is serverUrl, not url.

{
  "mcpServers": {
    "gemina": {
      "serverUrl": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

Append to ~/.codex/config.toml:

[mcp_servers.gemina]
url = "https://api.gemina.co/api/v1/mcp/"
http_headers = { "X-API-Key" = "<paste-your-key-here>" }

openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","headers":{"X-API-Key":"<paste-your-key-here>"}}'

Append under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  gemina:
    url: "https://api.gemina.co/api/v1/mcp/"
    headers:
      X-API-Key: "<paste-your-key-here>"