MCP Server

One hosted server, 13 tools for business documents. Sign in with OAuth 2.1 or send an API key. The FileTag tools are free up to 1,500 calls/month — no credit card.

Overview

The Gemina MCP server speaks Streamable HTTP. Mount it as a tool source in any compatible host — Claude Code, claude.ai, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Grok, ChatGPT, n8n, Copilot Studio, Zapier, Windsurf, Cline, OpenClaw, Hermes-Agent — or drive it from a script. Copy-paste config for each host lives on the Connect section of the MCP page.

MCP endpointhttps://api.gemina.co/api/v1/mcp/
TransportStreamable HTTP
Discovery (no credentials)https://api.gemina.co/api/v1/mcp/public/
Manifesthttps://www.gemina.co/.well-known/mcp.json

Keep the trailing slash on the endpoint. The slashless form is accepted and rewritten, but some hosts treat the redirect as a failed connection.

Authentication

Tool execution needs a credential. The anonymous discovery mount answers tools/list without one, so a host can inspect the catalog before an account exists.

Interactive

OAuth 2.1 — sign in from your app

Recommended

Register the server without a header. The host discovers the authorization server, opens a browser, and you sign in to Gemina and approve the connection. Each connected app gets its own key; revoke it any time under Connected apps in the console. The token carries the mcp scope.

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

# claude.ai and Claude Desktop
# Customize → Connectors → Add → Add custom connector → Paste the URL → Sign in
# URL: https://api.gemina.co/api/v1/mcp/

Most hosts need nothing beyond the URL. They register themselves on the first 401 and open your browser.

Three need an explicit second step. One can't sign in at all:

Codex CLI
codex mcp add gemina --url https://api.gemina.co/api/v1/mcp/ codex mcp login geminaA bare [mcp_servers.gemina] block in config.toml connects unauthenticated.
OpenClaw
openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","auth":"oauth"}' openclaw mcp login geminaBoth are required. OpenClaw has no 401-triggered sign-in.
Hermes-Agent
auth: oauth hermes mcp login geminaOAuth is an explicit opt-in in ~/.hermes/config.yaml. Run the login from a fresh terminal: the in-session config reload times out before a browser sign-in finishes.
Cline
API key onlyNo documented OAuth path for remote servers as of 27 August 2026. Use the API-key lane below.

Discovery documents:

  • https://api.gemina.co/.well-known/oauth-protected-resource/api/v1/mcpProtected resource metadata (RFC 9728)
  • https://api.gemina.co/.well-known/oauth-authorization-server/api/v1/mcpAuthorization server metadata (RFC 8414)
Automated

API key — headless and scripted

Send a Gemina API key on every request, as Authorization: Bearer or X-API-Key. Same server, same tools; the key you use for the REST API works here unchanged. Get one from the console.

Tools

13 tools in 3 groups. Names and descriptions are read from the published manifest at build time, so this page and the server cannot disagree.

FileTag

3 tools · Free tier

Tag, rename, and enrich any PDF or image. Free tier, no credit card.

  • files_create_uploadReserve a pre-signed PUT slot for a file the agent holds locally, then follow the returned next_tool_call recipe into tag_file. Bytes go straight from the agent host to storage and never traverse the LLM context.
  • tag_fileRun the FileTag pipeline against a previously uploaded slot. Returns extracted metadata, a suggested filename, six filename patterns, and a short-lived signed URL to an enriched copy with the metadata embedded in document properties or EXIF.
  • tag_urlFetch a public HTTPS URL server-side under strict SSRF guards and run the FileTag pipeline on it. Same result shape as tag_file; the bytes never traverse the LLM context.

Extraction

7 tools · Plan credits

Typed extraction over invoices, Hebrew documents, line items, raw OCR, and custom templates.

  • files_create_extraction_uploadReserve a pre-signed PUT slot for Core-OCR extraction. Distinct from the FileTag upload flow — follow the returned recipe into extract_document with one or more extraction_types.
  • extract_documentRun typed extraction on an uploaded slot. Choose extraction_types: ocr, invoice_headers, invoice_line_items, document_details_hebrew, document_line_items_hebrew, or custom_template. Asynchronous — returns the result directly or a correlationId to poll. Model selection and thinking, evaluation, correction, and coordinate toggles mirror the REST API.
  • get_extraction_resultPoll for the result of an asynchronous extract_document call using its correlationId. Returns the completed extraction, or an in-process status to poll again.
  • list_extractionsList past extractions, newest first. Filter by external_id, end_user_id, or an ISO date window, and paginate with skip and limit.
  • get_extractionFetch one extraction by id, including the full extracted data.
  • get_documentFetch one document by id, including all of its extractions.
  • submit_extraction_feedbackSubmit verified or corrected field values for a completed extraction and get back a per-field comparison summary. Each extraction accepts feedback once.

Document Intelligence

3 tools · Plan credits

Search the tenant's indexed documents and compute exact totals over them.

  • query_documentsSearch the tenant's indexed documents in structured mode (exact field filters), semantic mode (natural-language similarity), or hybrid mode (keyword and semantic fused with Reciprocal Rank Fusion). Returns matched documents with their extracted fields and scores.
  • aggregate_documentsCompute sums, averages, minimums, maximums, and counts over indexed documents, grouped by vendor, currency, document type, expense type, payment method, end user, month, or year. Money metrics are always split per currency unless a currency filter is given, so totals are never mixed.
  • index_documentManually (re)index one document into the searchable index — after corrections, or to backfill a document processed before indexing was enabled. Indexing otherwise happens automatically on every extraction once the tenant enables it.

Chat is deliberately not a tool: a conversation carries state between turns and an MCP call is stateless. Agents compose a conversational answer from query_documents and aggregate_documents instead.

Errors

Transport-level failures use HTTP status codes; tool failures come back as the standard Gemina error envelope inside the JSON-RPC result. Branch on error_code, not on the message.

  • 401 UNAUTHORIZED_ERROR — No credential was sent. An OAuth host reads the WWW-Authenticate challenge and starts the sign-in.
  • 403 ACCESS_DENIED_ERROR — The key is unknown, revoked or expired. Re-sending it will not help.
  • 403 insufficient_scope — The OAuth token does not carry the mcp scope. Reconnect the app.
  • 429 FILETAG_RATE_LIMIT_EXCEEDED — Burst limit. Wait the Retry-After header and retry.
  • 429 FILETAG_QUOTA_EXHAUSTED — The monthly free allowance is spent. Retry-After counts down to the reset; upgrading lifts it sooner.
  • 429 CREDIT_EXHAUSTED, INSUFFICIENT_CREDITS, SPEND_LIMIT_EXCEEDED — Extraction and Document Intelligence tools run on plan credits; retrying will not help until the reset or a plan change.

The full status-code table is in the REST API error reference.

Headless session with curl

Open a session with initialize, then list the tools. The same headers work for tools/call.

curl -X POST https://api.gemina.co/api/v1/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl -X POST https://api.gemina.co/api/v1/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Reference

Connect a host

Related docs

Limits

  • Files up to 50 MB
  • ~10 calls/second burst per key
  • 1,500 FileTag calls/month free

Connect an agent in a minute.

1,500 free FileTag calls a month. No credit card.

Connect your agentGet Free API Key