[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_135":136},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":49,"_69":70,"_71":72,"_73":74,"_75":76,"_77":78,"_79":-5,"_80":-5,"_81":82,"_83":49,"_84":-5,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96},"apiUrl","https://odel.app/api","creator","tommyil","moduleId","gemina-mcp","@tommyil/gemina-mcp","displayName","Gemina","tagline","Extract, search and tag any document: invoices, receipts, contracts, templates. OAuth or API key.","iconKey","https://www.gemina.co/assets/gemina-logo.png","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://api.gemina.co/api/v1/mcp/\",\"transport\":\"streamable-http\",\"authType\":\"headers\",\"requiredSecrets\":[{\"name\":\"X-API-Key\",\"scope\":\"per-user\",\"header\":\"X-API-Key\"}]}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363235000,"updatedAt",1788756225000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=co.gemina%2Fgemina","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1788728812000,"detectedTransport","streamable-http","detectedAuthType","oauth","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/tommyil/gemina-mcp","githubRepoFullName","tommyil/gemina-mcp","releaseId","ext-tommyil-gemina-mcp","version","2.1.0","descriptionMarkdown","

\n $\"Gemina\"$ \n\n# Gemina — MCP server\n\n**Tag, extract, and search your documents from any MCP client. Free tier: 1,500 FileTag tags/month, no credit card.**\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Free tier](https://img.shields.io/badge/free%20tier-1%2C500%20tags%2Fmonth-brightgreen.svg)](https://www.gemina.co/filetag)\n[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-purple.svg)](https://modelcontextprotocol.io)\n[![Last commit](https://img.shields.io/github/last-commit/tommyil/gemina-mcp.svg)](https://github.com/tommyil/gemina-mcp/commits/main)\n\n[Install](#quick-install) • [Examples](https://github.com/tommyil/gemina-mcp/blob/main/examples) • [Product page](https://www.gemina.co/product/agents) • [Full docs](https://www.gemina.co/docs/mcp)\n\n

\n\n---\n\n## What is this?\n\nThis repository is the **discovery, install, and examples surface** for Gemina's MCP server. The server itself is hosted at `https://api.gemina.co/api/v1/mcp/` — there is no daemon to run locally. Point your MCP-compatible client at the endpoint, sign in with your Gemina account (or paste an API key for headless use), and tag your first document in under a minute.\n\nOne server, three tool groups: **FileTag** (free tier — tag, rename, and enrich any PDF or image), **Extraction** (Core-OCR: invoice headers, line items, full text, custom templates), and **Document Intelligence** (search and aggregate over your indexed documents). See [Tools](#tools) for the full list.\n\nThe server itself is closed-source (operated by Gemina). Everything in this repo — install snippets, examples, integration code — is MIT-licensed and contributions are welcome.\n\n## What you get\n\nOne sign-in, three tool groups. Every group takes any PDF or image up to 50 MB (PDF, PNG, JPEG, GIF, WebP, HEIC/HEIF, AVIF).\n\n**1. FileTag — tag, rename, enrich (free tier).** Send a document, get structured metadata, six suggested filenames, and a downloadable copy with the metadata embedded in the file itself. Tools: `files_create_upload` → `tag_file`, or `tag_url`.\n\n**2. Extraction — pull the fields out (paid).** OCR for any document; ready-made models for invoice headers and invoice line items (plus Hebrew document details and line items); and **custom templates** — you define the fields, Gemina extracts them from any document type: contracts, forms, statements, delivery notes, IDs, anything. Tools: `files_create_extraction_upload` → `extract_document` → `get_extraction_result`, `list_extractions`, `get_extraction`, `get_document`, `submit_extraction_feedback` (send corrections back).\n\n**3. Document Intelligence — ask your archive (paid).** Every extraction is indexed. Search by vendor, date, amount, type or free text; get sums, averages and counts grouped by vendor, currency, type or month. Tools: `query_documents`, `aggregate_documents`, `index_document`.\n\n

Sample: FileTag output (click to expand)

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

\n\n

Sample: extraction output (abridged — extract_document with invoice_headers)

\n\n```json\n{\n \"status\": \"success\",\n \"meta\": { \"extractionType\": \"invoice_headers\", \"modelType\": \"invictus\", \"extractionId\": \"…\" },\n \"values\": {\n \"vendorName\": { \"value\": \"Acme Office Supplies Ltd.\", \"confidence\": 0.98 },\n \"documentDate\": { \"value\": \"2026-02-15\" },\n \"docNumber\": { \"value\": \"12345\" },\n \"netAmount\": { \"value\": 692.31 },\n \"vatAmount\": { \"value\": 117.69 },\n \"totalAmount\": { \"value\": 810.00 },\n \"currency\": { \"value\": \"USD\" }\n },\n \"document\": { \"documentId\": \"…\", \"externalId\": \"your-idempotency-key\" }\n}\n```\n\nWith `custom_template`, `values` contains exactly the fields you defined in the template.\n\n

\n\n

Sample: Document Intelligence (abridged — aggregate_documents)

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

\n\n## Quick install\n\n**Sign in with your Gemina account** — no API key to copy. Every snippet below points your client at the endpoint; the client discovers Gemina's authorization server and opens a browser sign-in. Don't have an account? Create one free (no credit card) at **https://console.gemina.co/registration/create-account**.\n\nRunning headless (CI, servers, scripts, or a client that doesn't prompt to sign in)? Use the **API-key form** shown under each client instead.\n\n**Endpoint:** `https://api.gemina.co/api/v1/mcp/` · **Transport:** Streamable HTTP · **Auth:** OAuth 2.1 sign-in (default) *or* `X-API-Key` header (headless)\n\n

How OAuth sign-in works (click to expand)

\n\n- Clients discover the authorization server from the MCP URL via RFC 9728 (protected-resource metadata) and RFC 8414 (authorization-server metadata):\n - `https://api.gemina.co/.well-known/oauth-protected-resource/api/v1/mcp`\n - `https://api.gemina.co/.well-known/oauth-authorization-server/api/v1/mcp`\n- Dynamic Client Registration (DCR) and Client ID Metadata Documents (CIMD) are both supported — no pre-registration, no client ID/secret to paste.\n- Scope: `mcp`. Access tokens last 1 hour; refresh tokens rotate and last 30 days.\n- Each connected app gets its own API key named ` (OAuth)`. See and revoke them under **Console → API Keys → Connected apps** at https://console.gemina.co.\n- 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.\n\n

\n\n

Claude Desktop / claude.ai

\n\n**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.\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Customize → Connectors\n2. Add → Add custom connector\n3. Paste the URL\n4. Sign in\n```\n\nSign in with your Gemina account when prompted and approve the consent page. The Gemina tools appear in new chats immediately.\n\n**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).\n\n**Prerequisites**\n\n1. **Node.js 18+** — install from [nodejs.org](https://nodejs.org/) (Windows: ensure \"Add to PATH\" stays checked; macOS/Linux: standard installer).\n2. **Claude Desktop capabilities** — open **Settings → Capabilities** and turn on:\n - Code execution and file creation\n - Allow network egress\n - Domain allowlist: **All domains** (or add `storage.googleapis.com` to the narrow allowlist — that's where signed enriched-file URLs are hosted).\n\n 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.\n\n**Config**\n\nIn Claude Desktop, **Settings → Developer → Edit Config** opens `claude_desktop_config.json` at:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nMerge the `mcpServers` block alongside any existing config:\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"https://api.gemina.co/api/v1/mcp/\",\n \"--header\",\n \"X-API-Key:${GEMINA_API_KEY}\"\n ],\n \"env\": {\n \"GEMINA_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\nSave → fully quit Claude Desktop (Cmd+Q / right-click tray → Quit) → relaunch. First launch may take 10–30s while `npx` downloads `mcp-remote`.\n\n**Notes**\n\n- No space after `X-API-Key:` in the `--header` arg — it's the documented workaround for `npx`'s shell-split parsing.\n- The env-var indirection (`${GEMINA_API_KEY}`) keeps the literal key out of `args`, where it could leak via process listings.\n- **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\"`.\n\n

\n\n

Claude Code (CLI)

\n\n**OAuth (default):** register the server, then run `/mcp` and sign in — Claude Code opens the Gemina sign-in in your browser.\n\n```bash\nclaude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/\n# then run /mcp and sign in\n```\n\nInside Claude Code: `/mcp` → select **gemina** → **Authenticate** → sign in with your Gemina account in the browser → approve the consent page.\n\n**API key (headless):**\n\n```bash\nclaude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \\\n --header \"X-API-Key: \"\n```\n\n

\n\n

Cursor

\n\nFile: `~/.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.\n\n**OAuth (default):**\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"url\": \"https://api.gemina.co/api/v1/mcp/\"\n }\n }\n}\n```\n\n**API key (headless):**\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"url\": \"https://api.gemina.co/api/v1/mcp/\",\n \"headers\": {\n \"X-API-Key\": \"\"\n }\n }\n }\n}\n```\n\n

\n\n

VS Code

\n\nFile: `.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**.\n\n**OAuth (default):**\n\n```json\n{\n \"servers\": {\n \"gemina\": {\n \"type\": \"http\",\n \"url\": \"https://api.gemina.co/api/v1/mcp/\"\n }\n }\n}\n```\n\n**API key (headless):**\n\n```json\n{\n \"servers\": {\n \"gemina\": {\n \"type\": \"http\",\n \"url\": \"https://api.gemina.co/api/v1/mcp/\",\n \"headers\": {\n \"X-API-Key\": \"\"\n }\n }\n }\n}\n```\n\n

\n\n

Cline

\n\nIn Cline's MCP settings (gear icon → MCP Servers → Edit Config), add:\n\n**OAuth (default):**\n\n> **Cline is API-key only.** As of 2026-08-27 Cline has no documented OAuth path\n> for remote MCP servers — its MCP docs never mention OAuth, and the one release\n> note that does (v4.1.7) names the legacy SSE transport, not `streamableHttp`.\n> Use the API-key form below.\n\n\n**API key (headless):**\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"type\": \"streamableHttp\",\n \"url\": \"https://api.gemina.co/api/v1/mcp/\",\n \"headers\": {\n \"X-API-Key\": \"\"\n }\n }\n }\n}\n```\n\n

\n\n

Windsurf

\n\nFile: `~/.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.\n\nThe 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.\n\n**OAuth (default):**\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"serverUrl\": \"https://api.gemina.co/api/v1/mcp/\"\n }\n }\n}\n```\n\n**API key (headless):**\n\n```json\n{\n \"mcpServers\": {\n \"gemina\": {\n \"serverUrl\": \"https://api.gemina.co/api/v1/mcp/\",\n \"headers\": {\n \"X-API-Key\": \"\"\n }\n }\n }\n}\n```\n\n

\n\n

Codex CLI

\n\n**OAuth (default):**\n\n```bash\ncodex mcp add gemina --url https://api.gemina.co/api/v1/mcp/\ncodex mcp login gemina\n```\n\n`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.\n\nFor the API-key lane, append to `~/.codex/config.toml`:\n\n**API key (headless):**\n\n```toml\n[mcp_servers.gemina]\nurl = \"https://api.gemina.co/api/v1/mcp/\"\nhttp_headers = { \"X-API-Key\" = \"\" }\n```\n\n

\n\n

OpenClaw

\n\n**OAuth (default):**\n\n```bash\nopenclaw mcp set gemina '{\"url\":\"https://api.gemina.co/api/v1/mcp/\",\"transport\":\"streamable-http\",\"auth\":\"oauth\"}'\nopenclaw mcp login gemina\n```\n\nBoth 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

`, and check it with `openclaw mcp doctor gemina --probe`.\n\n**API key (headless):**\n\n```bash\nopenclaw mcp set gemina '{\"url\":\"https://api.gemina.co/api/v1/mcp/\",\"transport\":\"streamable-http\",\"headers\":{\"X-API-Key\":\"\"}}'\n```\n\n

\n\n\nHermes-Agent
\n\nAppend under `mcp_servers` in `~/.hermes/config.yaml`:\n\n**OAuth (default):**\n\n```yaml\nmcp_servers:\n  gemina:\n    url: \"https://api.gemina.co/api/v1/mcp/\"\n    auth: oauth\n```\n\nThen 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.\n\n**API key (headless):**\n\n```yaml\nmcp_servers:\n  gemina:\n    url: \"https://api.gemina.co/api/v1/mcp/\"\n    headers:\n      X-API-Key: \"\"\n```\n\n
\n\n\nGrok
\n\nxAI'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.\n\n**OAuth (default):**\n\n```bash\ngrok mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/\n```\n\n**API key (headless):**\n\n```bash\ngrok mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \\\n  --header \"X-API-Key: \"\n```\n\n
\n\n\nGemini CLI
\n\nGoogle'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`.\n\n**OAuth (default):**\n\n```bash\ngemini mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/\n```\n\n**API key (headless):**\n\n```bash\ngemini mcp add --transport http \\\n  --header \"X-API-Key: \" \\\n  gemina https://api.gemina.co/api/v1/mcp/\n```\n\n
\n\n\nn8n
\n\nWorkflow 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.\n\n**OAuth (default):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Add the MCP Client Tool node (under an AI Agent), or MCP Client for a plain step\n2. MCP Endpoint URL: paste the URL above\n3. Server Transport: HTTP Streamable\n4. Authentication: MCP OAuth2\n5. Credentials -> create an \"MCP OAuth2 API\" credential; leave Dynamic Client\n   Registration on and Resource URL empty\n6. Click sign in, approve Gemina in the browser, then set Tools to Include\n```\n\n**API key (headless):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Add the MCP Client Tool node (under an AI Agent), or MCP Client for a plain step\n2. MCP Endpoint URL: paste the URL above\n3. Server Transport: HTTP Streamable\n4. Authentication: Header Auth -> Name: X-API-Key, Value: \n5. Set Tools to Include (All, or a subset)\n```\n\n
\n\n\nCopilot Studio
\n\nMicrosoft'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.\n\n**OAuth (default):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. In your agent: Tools -> Add a tool -> New tool -> Model Context Protocol\n2. Server name: Gemina\n3. Server URL: paste the URL above\n4. Authentication: OAuth 2.0 -> Type: Dynamic discovery\n5. Create -> Create a new connection -> Add to agent\n```\n\n**API key (headless):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. In your agent: Tools -> Add a tool -> New tool -> Model Context Protocol\n2. Server name: Gemina\n3. Server URL: paste the URL above\n4. Authentication: API key -> Type: Header -> Name: X-API-Key\n5. Create -> Create a new connection (paste ) -> Add to agent\n```\n\n
\n\n\nZapier
\n\nConnects Gemina's tools to 8,000+ apps through the **MCP Client** app (Beta). A connection form, not a config file.\n\n> **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.\n\n**OAuth (default):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Apps -> + Add connection -> MCP Client -> Add connection\n2. Server URL: paste the URL above\n3. Transport: Streamable HTTP\n4. OAuth: Yes (leave Bearer Token blank)\n5. Continue, then sign in to Gemina in the tab that opens\n```\n\n**API key (headless):**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Apps -> + Add connection -> MCP Client -> Add connection\n2. Server URL: paste the URL above\n3. Transport: Streamable HTTP\n4. OAuth: No\n5. Bearer Token: \n```\n\n
\n\n\nChatGPT
\n\nAdd Gemina as a custom MCP app in ChatGPT on the web. Needs Developer mode and a Pro, Plus, Business, Enterprise or Edu account.\n\n> **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.\n\n**Setup steps:**\n\n```text\nURL: https://api.gemina.co/api/v1/mcp/\n\n1. Settings -> Security and login -> turn on Developer mode\n2. Go to chatgpt.com/plugins and select +\n3. Name it \"Gemina\" and paste the URL above under Connection\n4. Create, then sign in to Gemina when ChatGPT prompts\n```\n\n
\n\n\nOpenAI Responses API
\n\nFor embedding Gemina in your own product: one tool entry turns the whole Gemina surface into an OpenAI-side capability.\n\n> **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.\n\n**API key:**\n\n```bash\ncurl https://api.openai.com/v1/responses \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -d '{\n    \"model\": \"gpt-5.6\",\n    \"input\": \"Extract the totals from the invoice I uploaded.\",\n    \"tools\": [{\n      \"type\": \"mcp\",\n      \"server_label\": \"gemina\",\n      \"server_url\": \"https://api.gemina.co/api/v1/mcp/\",\n      \"headers\": { \"X-API-Key\": \"\" },\n      \"require_approval\": \"never\"\n    }]\n  }'\n```\n\n\n\nFor the full machine-readable install guide (used by agents), see [`llms-install.md`](https://github.com/tommyil/gemina-mcp/blob/main/llms-install.md).\n\n## Free tier\n\n**Free tier: 1,500 FileTag tags per month. No credit card required.** Sign up at [gemina.co/filetag](https://www.gemina.co/filetag), then sign in from your MCP client — or grab an API key for headless use. The same key works for both MCP and the REST API.\n\nNeed more? Paid plans add larger monthly allowances, the extraction and document-intelligence tools, configurable data residency, and longer retention. See [pricing](https://www.gemina.co/pricing).\n\n## Tools\n\nOne endpoint, 13 tools in three groups, plus 2 prompts. Every tool is listed for every key; the extraction and document-intelligence groups require a paid plan (see [pricing](https://www.gemina.co/pricing)). Anonymous discovery (`tools/list`, `prompts/list`) is available at `https://api.gemina.co/api/v1/mcp/public/`.\n\n**FileTag (free tier)**\n\n| Tool | What it does |\n|---|---|\n| `files_create_upload` | Reserve a pre-signed PUT slot for a file you'll tag. Returns `file_id`, the upload URL, and the headers to echo on the PUT. |\n| `tag_file` | Run the FileTag pipeline on an uploaded slot: metadata, six filename patterns, and a short-lived enriched-file URL. |\n| `tag_url` | Fetch a public HTTPS URL server-side and tag it — the bytes never pass through the model context. |\n\n**Extraction (Core-OCR)**\n\n| Tool | What it does |\n|---|---|\n| `files_create_extraction_upload` | Reserve a pre-signed PUT slot for extraction (distinct from the FileTag slot). |\n| `extract_document` | Run one or more extraction types on an uploaded slot: `ocr`, `invoice_headers`, `invoice_line_items`, `document_details_hebrew`, `document_line_items_hebrew`, `custom_template`. |\n| `get_extraction_result` | Poll an asynchronous extraction by `meta.correlationId`. |\n| `list_extractions` | List past extractions, newest first, with filters and pagination. |\n| `get_extraction` | Fetch one extraction by id, including the full extracted data. |\n| `get_document` | Fetch one document by id, including all of its extractions. |\n| `submit_extraction_feedback` | Send verified/corrected field values back — the extraction-quality feedback loop. |\n\n**Document Intelligence**\n\n| Tool | What it does |\n|---|---|\n| `query_documents` | Search your indexed documents: `structured` filters, `semantic` similarity, or `hybrid` (best default). |\n| `aggregate_documents` | Sums/averages/min/max/counts over indexed documents, grouped by vendor, currency, type, month, and more. |\n| `index_document` | (Re)index one document into the searchable index — after corrections or to backfill. |\n\n**Prompts:** `explain_filename_patterns` (the six filename patterns and when to use each) · `explain_upload_flow` (`files_create_upload` → PUT → `tag_file`).\n\nThe full reference for each group is in [`llms-install.md`](https://github.com/tommyil/gemina-mcp/blob/main/llms-install.md#3-tools-exposed).\n\n## Use cases\n\n| Use case | Tools | Example |\n|---|---|---|\n| 🧾 **Invoice / receipt data entry** | `extract_document` (`invoice_headers`, `invoice_line_items`) → your accounting, ERP or spreadsheet | [`examples/bulk-tag-folder`](https://github.com/tommyil/gemina-mcp/blob/main/examples/bulk-tag-folder) |\n| 📄 **Any document, your fields** | `extract_document` with a `custom_template` (contracts, forms, statements, delivery notes, IDs) | — define the template in the [console](https://console.gemina.co) |\n| 📊 **Questions over your archive** | `query_documents`, `aggregate_documents` (\"total spend with vendor X in Q2\") | — |\n| 📥 **Email attachment triage** | FileTag: tag inbound attachments, route to folders by vendor/type | [`examples/gmail-attachment-triage`](https://github.com/tommyil/gemina-mcp/blob/main/examples/gmail-attachment-triage) |\n| 🔍 **RAG ingestion** | FileTag metadata on vector-store entries so retrieval can filter by vendor, date, type | [`examples/llamaindex-reader`](https://github.com/tommyil/gemina-mcp/blob/main/examples/llamaindex-reader) · [`examples/langchain-loader`](https://github.com/tommyil/gemina-mcp/blob/main/examples/langchain-loader) |\n| 📁 **Bulk document filing** | FileTag: walk a directory, rename every file to a consistent pattern | [`examples/bulk-tag-folder`](https://github.com/tommyil/gemina-mcp/blob/main/examples/bulk-tag-folder) |\n| ⚡ **Quickstart (curl)** | First tag in three minutes, no MCP client needed | [`examples/curl-quickstart`](https://github.com/tommyil/gemina-mcp/blob/main/examples/curl-quickstart) |\n| 🖥️ **Claude Desktop walkthrough** | Step-by-step setup with screenshots | [`examples/claude-desktop`](https://github.com/tommyil/gemina-mcp/blob/main/examples/claude-desktop) |\n\n## Why Gemina, not a raw LLM call?\n\nA naive \"ask the model to read this PDF\" pipeline breaks in production: hallucinated vendor names, inconsistent dates, no stable schema, no line-item arithmetic, no feedback loop, nothing to search afterwards.\n\n| | Raw LLM | Gemina |\n|---|---|---|\n| Structured output | Free text, requires parsing | Stable JSON schema per extraction type, or your own template fields |\n| Line items | Rows guessed from text | Column-aware line-item extraction with totals reconciliation |\n| Hallucinations | Frequent | Cross-checked, refuses when unsure; corrections fed back with `submit_extraction_feedback` |\n| Search & totals | Build your own index | Every extraction indexed; `query_documents` / `aggregate_documents` |\n| Filing | DIY | Six filename patterns + metadata-embedded copy (FileTag) |\n| Data residency | Wherever the model runs | You pick the region per account: EU, US, Israel or Asia |\n| Cost | $$ per call | Free tier: first 1,500 FileTag tags/month |\n\n## Privacy & trust\n\n- **No model training.** Your documents are never used to train AI models — Gemina's or anyone else's.\n- **7-day deletion.** Files are deleted within 7 days of upload (configurable per plan).\n- **Encryption.** AES-256 at rest, TLS 1.3 in transit.\n- **Compliance.** GDPR and CCPA compliant. Configurable data residency on paid plans.\n\nFull details on the [Gemina Trust Center](https://www.gemina.co/trust-center).\n\n## Documentation\n\n- 📖 **Full docs:** [gemina.co/docs/mcp](https://www.gemina.co/docs/mcp) — REST + MCP reference\n- 🤖 **Agent install guide:** [`llms-install.md`](https://github.com/tommyil/gemina-mcp/blob/main/llms-install.md) — machine-readable, used by AI agents auto-discovering the server\n- 🔌 **MCP manifest:** [gemina.co/.well-known/mcp.json](https://www.gemina.co/.well-known/mcp.json)\n- 🏷️ **REST endpoint reference:** [gemina.co/docs.md](https://www.gemina.co/docs.md)\n\n## Community & support\n\n- 🐛 [Bug reports](https://github.com/tommyil/gemina-mcp/issues/new?template=bug.yml)\n- 🆘 [Integration help](https://github.com/tommyil/gemina-mcp/issues/new?template=integration_help.yml)\n- 💬 [Discussions](https://github.com/tommyil/gemina-mcp/discussions)\n- ✉️ Email: [info@gemina.co](mailto:info@gemina.co)\n- 🔒 Security: see [SECURITY.md](https://github.com/tommyil/gemina-mcp/blob/main/SECURITY.md)\n\n## For aggregators and directory listings\n\nThe `Dockerfile` at the repo root is **not for end users.** It exists so directory operators (e.g. Glama's `/mcp/servers/` tier) can build a container that introspects the public tool surface without provisioning credentials. The container runs [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) against `https://api.gemina.co/api/v1/mcp/public/` — a read-only discovery endpoint that serves `initialize` / `tools/list` / `prompts/list` to anonymous callers but refuses `tools/call`. End users should follow the **Quick install** section above and connect to the authenticated endpoint by signing in (or with their personal API key).\n\n## Contributing\n\nExamples PRs welcome — see [CONTRIBUTING.md](https://github.com/tommyil/gemina-mcp/blob/main/CONTRIBUTING.md). The server itself is closed-source, so PRs that touch the actual MCP server logic will be declined, but bug reports against the live server are very welcome.\n\n## License\n\nThe contents of this repository — install snippets, example code, documentation, configuration files, and sample assets — are released under the [MIT License](https://github.com/tommyil/gemina-mcp/blob/main/LICENSE).\n\nThe Gemina MCP server itself is a hosted closed-source service operated by Gemina (https://gemina.co) and is **not** covered by this license. Use of the server is governed by [Gemina's Terms of Service](https://www.gemina.co/terms-of-service) and [Privacy Policy](https://www.gemina.co/privacy-policy).\n","changelogMarkdown","videoKey","requiredSecretsJson","[{\"name\":\"X-API-Key\",\"scope\":\"per-user\",\"header\":\"X-API-Key\"}]","publishedAt","priceCents","trialDays",0,"upstream",{"_119":120,"_121":122,"_123":124,"_125":126,"_127":128,"_129":130},"requiredSecrets",[113],"tags",[99,100,101,102,103,104,105,106,107,108,109,65,110,111,112],"assets",[],"stats",{"_97":86,"_98":86},"ratingAvg","reviewCount","claude","cursor","document-ai","document-extraction","document-search","email-automation","image-processing","invoice-processing","langchain","llamaindex","metadata","pdf","rag","remote-mcp",{"_114":115,"_116":117,"_118":115},"name","X-API-Key","scope","per-user","header","topics",[99,100,101,102,103,104,105,106,107,108,131,132,109,133,65,110,111,112,63,134],"license","MIT","language","Python","registryName","co.gemina/gemina","homepage","https://www.gemina.co/product/agents","packages",[],"mcp","mcp-server","model-context-protocol","vscode","ENV",{"_137":138,"_139":140,"_141":142},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]