Gemina Filetag

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

使用 custom_template 时，values 中恰好包含你在模板中定义的字段。

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

• 客户端通过 RFC 9728（受保护资源元数据）和 RFC 8414（授权服务器元数据），从 MCP URL 发现授权服务器：
  • https://api.gemina.co/.well-known/oauth-protected-resource/api/v1/mcp
  • https://api.gemina.co/.well-known/oauth-authorization-server/api/v1/mcp
• 同时支持动态客户端注册（DCR）和客户端 ID 元数据文档（CIMD）——无需预先注册，也无需粘贴客户端 ID/密钥。
• 作用域：mcp。访问令牌有效期为 1 小时；刷新令牌会轮换，有效期为 30 天。
• 每个已连接的应用都会获得一个名为 <app> (OAuth) 的 API 密钥。请前往 https://console.gemina.co 的 Console → API Keys → Connected apps 查看和撤销密钥。
• 大多数宿主只需填写 URL。三种宿主需要明确执行第二步——Codex CLI、OpenClaw 和 Hermes-Agent（见各自章节）；另有三种完全无法登录：Cline（截至 2026-08-27，没有针对远程服务的 OAuth 文档）、curl 和 OpenAI Responses API（不支持浏览器）。ChatGPT 则相反：它可以登录，但无法发送 API 密钥。

推荐方式：通过 Connectors 使用 OAuth。 claude.ai 和 Claude Desktop 使用相同的流程——无需配置文件、无需 mcp-remote，也无需 API 密钥。你批准后，Gemina 会为该应用创建一个密钥。

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

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

收到提示时，使用你的 Gemina 账户登录并批准授权页面。Gemina 工具会立即显示在新聊天中。

备用方式：通过 mcp-remote 使用 API 密钥。 Claude Desktop 的 Connectors 界面不接受自定义标头，因此 API 密钥必须通过 mcp-remote stdio 桥接程序传递。仅在需要使用特定密钥时使用此方式（无头环境或共享计算机）。

前提条件

1. Node.js 18+——从 nodejs.org 安装（Windows：确保“Add to PATH”保持勾选；macOS/Linux：使用标准安装程序）。

2. Claude Desktop 功能——打开 Settings → Capabilities 并启用：

   • 代码执行和文件创建
   • 允许网络出口
   • 域名允许列表：All domains（或将 storage.googleapis.com 添加到较严格的允许列表——签名后的增强文件 URL 托管于此）。

   如果未启用网络出口，tag_file/tag_url 会正确返回 JSON，但 Claude 无法从存储中获取增强文件 URL，你会看到“Host not in allowlist”。设置仅对新聊天生效——切换选项后，请新建对话。

配置

在 Claude Desktop 中，选择 Settings → Developer → Edit Config，即可打开以下位置的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

将 mcpServers 配置块合并到现有配置中：

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

保存 → 完全退出 Claude Desktop（Cmd+Q / 右键点击系统托盘图标 → Quit）→ 重新启动。首次启动可能需要 10–30 秒，因为 npx 会下载 mcp-remote。

注意事项

• --header 参数中的 X-API-Key: 后不要加空格——这是 npx shell 分割解析的文档所述解决方法。
• 环境变量间接引用（${GEMINA_API_KEY}）可避免将明文密钥放入 args，以免通过进程列表泄露。
• Windows + spawn npx ENOENT：Claude Desktop 不会继承 shell 的 PATH。将 "command": "npx" 替换为在 PowerShell 中运行 where npx 得到的绝对路径（JSON 中可使用正斜杠），例如 "C:/Program Files/nodejs/npx.cmd"。

**OAuth（默认）：**注册服务，然后运行 /mcp 并登录——Claude Code 会在浏览器中打开 Gemina 登录页面。

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

在 Claude Code 中：/mcp → 选择 gemina → Authenticate → 在浏览器中使用你的 Gemina 账户登录 → 在授权页面批准。

API 密钥（无头模式）：

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

文件：~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。Cursor 会动态注册自身，并在首次收到 401 时打开浏览器——文件中无需填写客户端 ID 或密钥。

OAuth（默认）：

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

API 密钥（无头模式）：

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

文件：.vscode/mcp.json（当前工作区），或从命令面板运行 MCP: Open User Configuration，以用于所有工作区。VS Code 会动态注册，并在首次连接时打开浏览器；确认信任提示，然后在 Accounts → Manage Trusted MCP Servers 下找到该账户。

OAuth（默认）：

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

API 密钥（无头模式）：

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

在 Cline 的 MCP 设置中（齿轮图标 → MCP Servers → Edit Config）添加：

OAuth（默认）：

**Cline 仅支持 API 密钥。**截至 2026-08-27，Cline 没有针对远程 MCP 服务的文档所述 OAuth 路径——其 MCP 文档从未提及 OAuth，而唯一提及 OAuth 的发行说明（v4.1.7）指的是旧版 SSE 传输，而非 streamableHttp。 请使用下方的 API 密钥配置。

API 密钥（无头模式）：

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

文件：~/.codeium/windsurf/mcp_config.json，或使用 Cascade 面板中的 MCP 图标。远程服务使用 serverUrl（也支持 url），然后重新加载 MCP 列表。目前已作为 Devin Desktop 发布——Windsurf 文档会重定向到该产品。

文档称 Cascade“支持每种传输类型的 OAuth”，但没有说明明确的登录步骤，因此如果没有出现浏览器提示，请使用 API 密钥配置。

OAuth（默认）：

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

API 密钥（无头模式）：

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

OAuth（默认）：

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

codex mcp add 会检测 URL 上的 OAuth，通常会自行启动浏览器登录；codex mcp login 则是文档所述的可靠方式。OAuth 场景下不要粘贴单独的 [mcp_servers.gemina] 配置块——Codex 会在未经身份验证的情况下连接服务，导致每次工具调用都失败。已于 2026-08-27 在 codex-cli 0.150.1 上验证。

对于 API 密钥方式，将以下内容追加到 ~/.codex/config.toml：

API 密钥（无头模式）：

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

OAuth（默认）：

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

两行都必须添加。mcp set 会以 auth: "oauth" 保存服务；mcp login 会启动认证流程——OpenClaw 不会在收到 401 时自行启动 OAuth。在无头机器上，使用 openclaw mcp login gemina --code <code> 传回代码，并通过 openclaw mcp doctor gemina --probe 检查。

API 密钥（无头模式）：

openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","headers":{"X-API-Key":"<paste-your-key-here>"}}'

在 ~/.hermes/config.yaml 的 mcp_servers 下追加：

OAuth（默认）：

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

然后在全新的终端中运行 hermes mcp login gemina，不要在正在运行的会话中执行——会话内重新加载配置会在 30 秒后超时，时间不足以完成浏览器登录。auth: oauth 这一行用于启用 OAuth；Hermes 不会根据 401 自动推断。

API 密钥（无头模式）：

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

xAI 的编码 Agent。使用 curl -fsSL https://x.ai/cli/install.sh | bash 安装。首次使用时，OAuth 会启动浏览器流程；令牌会缓存于 ~/.grok/mcp_credentials.json。也可在 grok.com 上操作：Connectors → New Connector → Custom，粘贴 URL。

OAuth（默认）：

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

API 密钥（无头模式）：

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

Google 的终端 Agent。添加 -s user，即可为每个项目安装 Gemina。OAuth 无需配置任何内容——默认的 dynamic_discovery 提供方会在收到 401 响应时自动注册并打开浏览器；令牌会缓存于 ~/.gemini/mcp-oauth-tokens.json。使用 /mcp auth gemina 重新登录。

OAuth（默认）：

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

API 密钥（无头模式）：

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

云端或可自托管的工作流自动化工具。在 AI Agent 下使用 MCP Client Tool 节点，或将 MCP Client 用作普通工作流步骤。对于 OAuth，创建 MCP OAuth2 API 凭据，并保持启用 Dynamic Client Registration，同时将 Resource URL 留空——n8n 会向 Gemina 注册。需要 MCP Client Tool 节点 v1.2 或更高版本。

OAuth（默认）：

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 密钥（无头模式）：

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 的 Agent 构建工具——通过浏览器向导操作，无需配置文件。Dynamic discovery 是合适的方式：Gemina 会发布 DCR 和发现文档，因此无需输入客户端 ID、密钥或端点 URL。Copilot Studio 仅支持 Streamable 传输。MCP 访问通过 Power Platform 连接器进行，因此会受租户 DLP 策略约束。

OAuth（默认）：

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 密钥（无头模式）：

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

通过 MCP Client 应用（Beta），将 Gemina 的工具连接到 8,000 多个应用。使用连接表单，而非配置文件。

仅支持 Bearer。 Zapier 没有自定义标头字段，因此密钥需填写在 Bearer Token 框中——Gemina 会将其作为 Authorization: Bearer 接受。这里不支持 X-API-Key 方式。

OAuth（默认）：

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 密钥（无头模式）：

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>

在网页版 ChatGPT 中将 Gemina 添加为自定义 MCP 应用。需要启用开发者模式，并使用 Pro、Plus、Business、Enterprise 或 Edu 账户。

仅支持 OAuth。 ChatGPT 无法向远程 MCP 服务发送自定义标头或 API 密钥，因此不支持无头模式——请改为登录；如果需要使用特定密钥，请使用 Codex CLI。

设置步骤：

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

如需将 Gemina 嵌入自己的产品：只需添加一个工具条目，即可将 Gemina 的全部功能转化为 OpenAI 端的能力。

仅支持 API 密钥。 这是服务端方式，不涉及浏览器，因此无需运行 OAuth 登录——API 会转发你已有的凭据。

API 密钥：

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