Gemina FileTag — MCP server

Tag, rename, and enrich any PDF or image. One MCP call. Free tier: 1,500 tags/month, no credit card.

Install • Examples • Product page • Full docs

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.

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

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

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

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

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

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

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

[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>"}}'

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: info@gemina.co
• 🔒 Security: see SECURITY.md

For aggregators and directory listings

The 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 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 with their personal API key.

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.