Gemina FileTag — MCP server

What is this?

This repository is the discovery, install, and examples surface for Gemina FileTag'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, paste an API key, and tag your first document in under a minute.

The server itself is closed-source (operated by Gemina). Everything in this repo — install snippets, examples, integration code — is MIT-licensed and contributions are welcome.

What you get

Send a PDF or image. Get back structured metadata, six suggested filenames, and a downloadable copy with metadata already embedded in the file itself.

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.

Quick install

You need an API key. Get one free (no credit card) at https://console.gemina.co/registration/create-account, then drop the snippet below into your MCP client's config and restart it.

Endpoint: https://api.gemina.co/api/v1/mcp/ · Transport: Streamable HTTP · Auth: X-API-Key header

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

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

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

For the full machine-readable install guide (used by agents), see llms-install.md.

Free tier

1,500 tags per month. No credit card required. Sign up at gemina.co/filetag, grab an API key, paste it into your config. The same key works for both MCP and the REST API.

Need more? Paid plans add larger monthly allowances, configurable data residency, and longer retention. See pricing.

Use cases

The same MCP call (tag_file or tag_url) powers all of these. Each example has a dedicated walkthrough in examples/.

Why FileTag, not a raw LLM call?

A naive "ask GPT to tag this PDF" pipeline breaks in production: hallucinated vendor names, inconsistent date formats, no structured output, no PDF metadata embedding, no enriched-file roundtrip. FileTag is the harness around that call — specialized agents that reason, cross-check, and refuse to guess — wrapped in a single endpoint with a stable JSON contract.

Privacy & trust

• No model training. Your documents are never used to train AI models — Gemina's or anyone else's.
• 7-day deletion. Files are deleted within 7 days of upload (configurable per plan).
• Encryption. AES-256 at rest, TLS 1.3 in transit.
• Compliance. GDPR and CCPA compliant. Configurable data residency on paid plans.

Full details on the Gemina Trust Center.

Documentation

• 📖 Full docs: gemina.co/docs/filetag — REST + MCP reference
• 🤖 Agent install guide: llms-install.md — machine-readable, used by AI agents auto-discovering the server
• 🔌 MCP manifest: gemina.co/.well-known/mcp.json
• 🏷️ REST endpoint reference: gemina.co/docs.md

Community & support

• 🐛 Bug reports
• 🆘 Integration help
• 💬 Discussions
• ✉️ Email: [email protected]
• 🔒 Security: see SECURITY.md

Contributing

Examples PRs welcome — see 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.

License

The contents of this repository — install snippets, example code, documentation, configuration files, and sample assets — are released under the MIT License.

The Gemina FileTag 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 and Privacy Policy.