{
  "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"
}

{
  "status": "success",
  "meta": { "extractionType": "invoice_headers", "modelType": "invictus", "extractionId": "…" },
  "values": {
    "vendorName":   { "value": "Acme Office Supplies Ltd.", "confidence": 0.98 },
    "documentDate": { "value": "2026-02-15" },
    "docNumber":    { "value": "12345" },
    "netAmount":    { "value": 692.31 },
    "vatAmount":    { "value": 117.69 },
    "totalAmount":  { "value": 810.00 },
    "currency":     { "value": "USD" }
  },
  "document": { "documentId": "…", "externalId": "your-idempotency-key" }
}

With custom_template, values contains exactly the fields you defined in the template.

{
  "rows": [
    { "group": { "vendor_name": "Acme Office Supplies Ltd.", "currency": "USD" }, "values": { "sum_total_amount": 810.0, "count": 1 } },
    { "group": { "vendor_name": "BluePeak Cafe",            "currency": "USD" }, "values": { "sum_total_amount": 26.19, "count": 1 } }
  ]
}

• Clients discover the authorization server from the MCP URL via RFC 9728 (protected-resource metadata) and RFC 8414 (authorization-server metadata):
  • https://api.gemina.co/.well-known/oauth-protected-resource/api/v1/mcp
  • https://api.gemina.co/.well-known/oauth-authorization-server/api/v1/mcp
• Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD) are both supported — no pre-registration, no client ID/secret to paste.
• Scope: mcp. Access tokens last 1 hour; refresh tokens rotate and last 30 days.
• Each connected app gets its own API key named <app> (OAuth). See and revoke them under Console → API Keys → Connected apps at https://console.gemina.co.
• Most hosts need nothing beyond the URL. Three need an explicit second step — Codex CLI, OpenClaw and Hermes-Agent (see their sections) — and three can't sign in at all: Cline (no documented OAuth for remote servers as of 2026-08-27), curl and the OpenAI Responses API (no browser). ChatGPT is the mirror case: it signs in, but cannot send an API key.

Recommended: OAuth via Connectors. claude.ai and Claude Desktop use the same flow — no config file, no mcp-remote, no API key. Gemina creates a key for the app when you approve it.

URL: https://api.gemina.co/api/v1/mcp/

1. Customize → Connectors
2. Add → Add custom connector
3. Paste the URL
4. Sign in

Sign in with your Gemina account when prompted and approve the consent page. The Gemina tools appear in new chats immediately.

Fallback: API key via mcp-remote. Claude Desktop's Connectors UI doesn't accept custom headers, so an API key has to go through the mcp-remote stdio bridge. Use this only if you need a specific key (headless or shared machines).

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".

OAuth (default): register the server, then run /mcp and sign in — Claude Code opens the Gemina sign-in in your browser.

claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/
# then run /mcp and sign in

Inside Claude Code: /mcp → select gemina → Authenticate → sign in with your Gemina account in the browser → approve the consent page.

API key (headless):

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

File: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor registers itself dynamically and opens your browser on the first 401 — no client ID or secret in the file.

OAuth (default):

{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/"
    }
  }
}

API key (headless):

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

File: .vscode/mcp.json (per workspace), or run MCP: Open User Configuration from the Command Palette for all of them. VS Code registers dynamically and opens a browser on first connection; confirm the trust prompt, then find the account under Accounts → Manage Trusted MCP Servers.

OAuth (default):

{
  "servers": {
    "gemina": {
      "type": "http",
      "url": "https://api.gemina.co/api/v1/mcp/"
    }
  }
}

API key (headless):

{
  "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:

OAuth (default):

Cline is API-key only. As of 2026-08-27 Cline has no documented OAuth path for remote MCP servers — its MCP docs never mention OAuth, and the one release note that does (v4.1.7) names the legacy SSE transport, not streamableHttp. Use the API-key form below.

API key (headless):

{
  "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, or the MCPs icon in the Cascade panel. Remote servers take serverUrl (url also works), then reload the MCP list. Now shipped as Devin Desktop — the Windsurf docs redirect there.

The docs say Cascade "supports OAuth for each transport type" but describe no explicit sign-in step, so if no browser prompt appears, use the API-key form.

OAuth (default):

{
  "mcpServers": {
    "gemina": {
      "serverUrl": "https://api.gemina.co/api/v1/mcp/"
    }
  }
}

API key (headless):

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

OAuth (default):

codex mcp add gemina --url https://api.gemina.co/api/v1/mcp/
codex mcp login gemina

codex mcp add detects OAuth on the URL and usually starts the browser sign-in by itself; codex mcp login is the documented guarantee. Do not paste a bare [mcp_servers.gemina] block for OAuth — Codex will connect to the server unauthenticated and every tool call fails. Verified against codex-cli 0.150.1 on 2026-08-27.

For the API-key lane, append to ~/.codex/config.toml:

API key (headless):

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

OAuth (default):

openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login gemina

Both lines are required. mcp set stores the server with auth: "oauth"; mcp login runs the flow — OpenClaw does not start OAuth off a 401 on its own. On a headless box, pass the code back with openclaw mcp login gemina --code <code>, and check it with openclaw mcp doctor gemina --probe.

API key (headless):

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:

OAuth (default):

mcp_servers:
  gemina:
    url: "https://api.gemina.co/api/v1/mcp/"
    auth: oauth

Then run hermes mcp login gemina from a fresh terminal, not inside a live session — the in-session config reload times out at 30s, too short for a browser sign-in. The auth: oauth line is what turns OAuth on; Hermes never infers it from a 401.

API key (headless):

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

xAI's coding agent. Install with curl -fsSL https://x.ai/cli/install.sh | bash. OAuth triggers a browser flow on first use; tokens cache in ~/.grok/mcp_credentials.json. On grok.com instead: Connectors → New Connector → Custom, paste the URL.

OAuth (default):

grok mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/

API key (headless):

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

Google's terminal agent. Add -s user to install Gemina for every project. Nothing to configure for OAuth — the default dynamic_discovery provider registers itself off the 401 and opens your browser; tokens cache in ~/.gemini/mcp-oauth-tokens.json. Re-run the sign-in with /mcp auth gemina.

OAuth (default):

gemini mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/

API key (headless):

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

Workflow automation, cloud or self-hosted. Use the MCP Client Tool node under an AI Agent, or MCP Client for a plain workflow step. For OAuth, create an MCP OAuth2 API credential and leave Dynamic Client Registration on with Resource URL empty — n8n registers itself with Gemina. Needs MCP Client Tool node v1.2 or later.

OAuth (default):

URL: https://api.gemina.co/api/v1/mcp/

1. Add the MCP Client Tool node (under an AI Agent), or MCP Client for a plain step
2. MCP Endpoint URL: paste the URL above
3. Server Transport: HTTP Streamable
4. Authentication: MCP OAuth2
5. Credentials -> create an "MCP OAuth2 API" credential; leave Dynamic Client
   Registration on and Resource URL empty
6. Click sign in, approve Gemina in the browser, then set Tools to Include

API key (headless):

URL: https://api.gemina.co/api/v1/mcp/

1. Add the MCP Client Tool node (under an AI Agent), or MCP Client for a plain step
2. MCP Endpoint URL: paste the URL above
3. Server Transport: HTTP Streamable
4. Authentication: Header Auth -> Name: X-API-Key, Value: <paste-your-key-here>
5. Set Tools to Include (All, or a subset)

Microsoft's agent builder — a browser wizard, no config file. Dynamic discovery is the right lane: Gemina publishes DCR and the discovery documents, so no client ID, secret or endpoint URL has to be typed. Copilot Studio supports the Streamable transport only. MCP access flows through Power Platform connectors, so tenant DLP policies apply.

OAuth (default):

URL: https://api.gemina.co/api/v1/mcp/

1. In your agent: Tools -> Add a tool -> New tool -> Model Context Protocol
2. Server name: Gemina
3. Server URL: paste the URL above
4. Authentication: OAuth 2.0 -> Type: Dynamic discovery
5. Create -> Create a new connection -> Add to agent

API key (headless):

URL: https://api.gemina.co/api/v1/mcp/

1. In your agent: Tools -> Add a tool -> New tool -> Model Context Protocol
2. Server name: Gemina
3. Server URL: paste the URL above
4. Authentication: API key -> Type: Header -> Name: X-API-Key
5. Create -> Create a new connection (paste <paste-your-key-here>) -> Add to agent

Connects Gemina's tools to 8,000+ apps through the MCP Client app (Beta). A connection form, not a config file.

Bearer only. Zapier has no custom-header field, so the key goes in the Bearer Token box — Gemina accepts it as Authorization: Bearer. There is no X-API-Key lane here.

OAuth (default):

URL: https://api.gemina.co/api/v1/mcp/

1. Apps -> + Add connection -> MCP Client -> Add connection
2. Server URL: paste the URL above
3. Transport: Streamable HTTP
4. OAuth: Yes (leave Bearer Token blank)
5. Continue, then sign in to Gemina in the tab that opens

API key (headless):

URL: https://api.gemina.co/api/v1/mcp/

1. Apps -> + Add connection -> MCP Client -> Add connection
2. Server URL: paste the URL above
3. Transport: Streamable HTTP
4. OAuth: No
5. Bearer Token: <paste-your-key-here>

Add Gemina as a custom MCP app in ChatGPT on the web. Needs Developer mode and a Pro, Plus, Business, Enterprise or Edu account.

OAuth only. ChatGPT cannot send a custom header or an API key to a remote MCP server, so there is no headless lane here — sign in instead, or use Codex CLI if you need a specific key.

Setup steps:

URL: https://api.gemina.co/api/v1/mcp/

1. Settings -> Security and login -> turn on Developer mode
2. Go to chatgpt.com/plugins and select +
3. Name it "Gemina" and paste the URL above under Connection
4. Create, then sign in to Gemina when ChatGPT prompts

For embedding Gemina in your own product: one tool entry turns the whole Gemina surface into an OpenAI-side capability.

API key only. This is a server-side lane with no browser, so there is no OAuth sign-in to run — the API forwards a credential you already hold.

API key:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "input": "Extract the totals from the invoice I uploaded.",
    "tools": [{
      "type": "mcp",
      "server_label": "gemina",
      "server_url": "https://api.gemina.co/api/v1/mcp/",
      "headers": { "X-API-Key": "<paste-your-key-here>" },
      "require_approval": "never"
    }]
  }'