Fingerprint

Fingerprint MCP 服务

功能

• 在本地运行，或使用托管实例 https://mcp.fpjs.io/mcp（在 Claude 中，可从连接器目录添加）
• 事件工具：检索和搜索识别事件与 Automation Intelligence（边缘）事件，并获取完整的智能信号数据
• 管理工具：管理工作区环境、API 密钥和自定义子域名
• 技能工具：向无法自行获取技能的客户端提供 Fingerprint 技能（集成指南、代理设置、Smart Signals）
• 同时支持 stdio 和 streamable-http 传输方式
• 可选使用 TLS 证书启用 HTTPS
• 支持 OAuth2 登录
• 面向多租户部署的公共模式（通过 JWT bearer token 传递 API 密钥）
• 工具筛选，用于控制公开哪些工具
• 可通过环境变量或 CLI 标志进行配置
• 支持 Docker，便于部署

安装

从源代码安装

go install github.com/fingerprintjs/fingerprint-mcp-server@latest

本地构建

git clone https://github.com/fingerprintjs/fingerprint-mcp-server.git
cd fingerprint-mcp-server
make build

make build 会运行 go generate（下载 OpenAPI 规范并在 internal/schema/ 下生成架构文件），然后构建二进制文件。

配置

可以通过 CLI 标志或环境变量配置服务：

CLI 标志	环境变量	默认值	说明
--serverapikey	FINGERPRINT_SERVER_API_KEY		Fingerprint Server API 密钥（私有模式）
--serverapiurl	FINGERPRINT_SERVER_API_URL	api.fpjs.io	自定义 Server API URL（省略则使用默认值）
--managementapikey	FINGERPRINT_MANAGEMENT_API_KEY		Fingerprint Management API 密钥（私有模式）
--managementapiurl	FINGERPRINT_MANAGEMENT_API_URL	management-api.fpjs.io	自定义 Management API URL（省略则使用默认值）
--region	FINGERPRINT_REGION	us	API 区域：us、eu 或 ap（私有模式）
--transport	MCP_TRANSPORT	stdio	传输方式：stdio 或 streamable-http
--port	MCP_PORT	8080	HTTP/HTTPS 服务的端口
--tlscert	MCP_TLS_CERT		TLS 证书文件路径
--tlskey	MCP_TLS_KEY		TLS 私钥文件路径
--readonly	MCP_READ_ONLY	false	仅公开读取工具（--tools 的简写，指定只读工具）
--tools	MCP_TOOLS		要注册的工具名称列表，以逗号分隔（覆盖 --readonly）
--publicmode	MCP_PUBLIC	false	公共模式：从 JWT bearer 令牌中提取 API 密钥
--authtoken	MCP_AUTH_TOKEN	（私有模式下自动生成）	访问服务所需的 Bearer 令牌（私有模式）
--jwtpublickey	FINGERPRINT_PUBLIC_KEY		用于验证 Fingerprint 签发的 JWT 令牌的 PEM 编码 ES256 公钥
--oauthresource	OAUTH_RESOURCE		此服务的 URL（用于 OAuth 元数据）
--oauthauthorizationserver	OAUTH_AUTH_SERVER		OAuth 授权服务的 URL
--jwksurl	JWKS_URL		用于在公共模式下验证 JWT 令牌的 JWKS URL
--openaiappschallengetoken	OPENAI_APPS_CHALLENGE_TOKEN		在 /.well-known/openai-apps-challenge 提供的域名验证令牌

遥测

此二进制文件默认关闭遥测。它没有内置的分析后端，默认发射器也是空操作，因此运行 OSS 二进制文件不会向任何人发送数据。

服务提供了一个钩子（analytics 包中的 analytics.Emitter），会在每个 MCP 方法调用时触发。想要进行产品分析的嵌入方可以将此包作为库导入，并在构建服务时调用 WithAnalytics(emitter)，以注册自己的发射器。Fingerprint 的托管版本（mcp.fpjs.io）使用了 Amplitude 发射器，但该实现位于私有托管仓库中，不在此处。

如果你要构建自己的发射器，事件格式见 analytics/analytics.go。中间件会为每个 MCP 方法触发一个 mcp_method_called 事件，并且只有在 subscription_id 非空时才会触发（因此，预认证方法和私有模式的认证路径始终不会触发事件）。通过 call_tool 或 call_write_tool 发起的调用，会将代理报告为 tool_name，将其受命运行的工具报告为 target_tool；即使代理拒绝该调用也一样（此时 is_error 为 true）。

请求检查

嵌入方可以注册第二个钩子（requestinspect 包中的 requestinspect.Inspector），以接收每个发往 /mcp 端点的 HTTP 请求元数据——方法、URL、原始标头和 TCP 对端地址，适用于审计日志记录和流量分析。构建服务时，使用 WithRequestInspector(inspector) 注册该钩子。OSS 二进制文件未配置检查器，因此不会收集任何信息。

此钩子的完整约定（时序、故障时放行行为、只读字段、stdio）记录在 requestinspect/requestinspect.go 中，该文件是此钩子的权威说明。有关完整的嵌入方实现框架（有界队列、后台传输、标头脱敏、优雅清理），请参阅 requestinspect/example_test.go。

用法

私有模式与公共模式

私有模式是指服务预先配置了 API 密钥（FINGERPRINT_SERVER_API_KEY 和 FINGERPRINT_MANAGEMENT_API_KEY）。当你运行一个供组织内部使用的本地实例时，此模式很有用：服务会自动使用配置中指定的密钥。在此模式下，必须提供认证令牌（MCP_AUTH_TOKEN），以防止未经认证的用户使用你的 MCP 服务。

公共模式是 https://mcp.fpjs.io/mcp 的运行模式。此模式适用于单个实例供不同组织的不同用户使用，且每位用户都有自己的 API 密钥的场景。在此模式下，API 密钥从由 https://dashboard.fingerprint.com 签发的 JWT 访问令牌中提取，或者由用户通过 OAuth2 流程获取。

Stdio 传输（默认）

export FINGERPRINT_SERVER_API_KEY=your-secret-api-key
./fingerprint-mcp-server

Streamable HTTP 传输

export FINGERPRINT_SERVER_API_KEY=your-secret-api-key
./fingerprint-mcp-server --transport=streamable-http --port=8080

MCP 端点将在 http://localhost:8080/mcp 提供。

HTTPS

提供 TLS 证书和密钥文件以启用 HTTPS：

./fingerprint-mcp-server --transport=streamable-http \
  --tlscert=cert.pem --tlskey=key.pem

工具筛选

默认情况下，会根据已配置的 API 密钥注册所有工具。你可以限制公开哪些工具：

# Only expose read-only tools
./fingerprint-mcp-server --readonly

# Expose a specific set of tools
./fingerprint-mcp-server --tools=get_event,search_events,list_environments

设置 --tools 时，它会覆盖 --readonly。

Docker

构建镜像

docker build -t fingerprint-mcp-server .

使用 Stdio 传输运行

docker run -i --rm \
  -e FINGERPRINT_SERVER_API_KEY=your-secret-api-key \
  fingerprint-mcp-server

使用 Streamable HTTP 传输运行

docker run -d --rm \
  -e FINGERPRINT_SERVER_API_KEY=your-secret-api-key \
  -e MCP_TRANSPORT=streamable-http \
  -p 8080:8080 \
  fingerprint-mcp-server

MCP 客户端配置

托管端点（托管式）

托管实例 https://mcp.fpjs.io/mcp 以公开模式运行，并通过 OAuth2 对每位用户进行身份验证。无需运行或配置任何内容。

在 Claude 中，请从连接器目录添加，而不是添加为自定义连接器：打开 自定义 > 连接器，选择 浏览连接器，然后搜索 Fingerprint。claude.ai、桌面端、移动端和 Claude Code 使用同一个目录，因此每个账户只需设置一次。

添加为自定义连接器仍然可行，但你必须自行命名，而且名称中的某些字符会导致工具发现失败，尽管连接器仍会显示为已连接。

在其他客户端中，直接使用该 URL：

{
  "mcpServers": {
    "fingerprint": {
      "type": "http",
      "url": "https://mcp.fpjs.io/mcp"
    }
  }
}

自托管

添加到 Cursor/Claude Desktop 等客户端的配置文件中（例如 claude_desktop_config.json）：

Stdio 传输：

{
  "mcpServers": {
    "fingerprint": {
      "command": "/path/to/fingerprint-mcp-server",
      "env": {
        "FINGERPRINT_SERVER_API_KEY": "your-secret-api-key"
      }
    }
  }
}

Streamable HTTP 传输：

{
  "mcpServers": {
    "fingerprint": {
      "url": "https://url/mcp",
      "headers": {
        "Authorization": "Bearer <auth-token>"
      }
    }
  }
}

使用 Stdio 的 Docker：

{
  "mcpServers": {
    "fingerprint": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FINGERPRINT_SERVER_API_KEY=your-secret-api-key", "fingerprint-mcp-server"]
    }
  }
}

可用工具

事件工具需要 Server API 密钥。管理工具需要 Management API 密钥。get_current_time 和技能工具无需密钥。get_skill 和 get_skill_file 不在 MCP 工具列表中：请通过 call_tool 运行它们。使用 --tools 时，请将 list_skills、get_skill、get_skill_file 和 call_tool 加入允许列表，技能才能正常使用。设置 --readonly 或通过 --tools 排除写入工具（创建/更新/删除/验证/连接）时，这些工具会被隐藏。

工具	描述
get_current_time	返回 UTC 当前日期/时间（以及可选的 IANA 时区）
list_skills	按 ID 和描述列出 Fingerprint 技能
get_skill	返回某项技能的说明及其引用的文件
get_skill_file	返回技能中的一个文件，例如代码片段
get_event	按 ID（识别或边缘）检索特定事件
search_events	使用筛选条件搜索事件（访客、IP、智能信号、时间范围）
list_environments	分页列出工作区环境
get_api_key	获取特定 API 密钥的详细信息
list_api_keys	按类型/状态/环境筛选并列出 API 密钥
create_environment	创建新的工作区环境
update_environment	更新现有工作区环境
delete_environment	删除工作区环境
create_api_key	创建新的 API 密钥（public/secret/proxy）
update_api_key	更新现有 API 密钥
delete_api_key	删除 API 密钥（不可撤销）
list_subdomains	分页列出自定义子域名
get_subdomain	获取子域名状态和 DNS 记录
create_subdomain	注册主机名并返回所需的 DNS 记录
verify_subdomain	请求一次 DNS 检查，然后返回刚读取的状态
connect_subdomain	获取 Domain Connect 链接，以便在服务提供商处添加 DNS 记录

对于自定义子域名，请通过技能工具遵循 fingerprint-proxy-integration。创建子域名不会添加 DNS 记录：如果服务提供商支持 Domain Connect，connect_subdomain 会返回一个链接，用户打开后即可通过一次确认添加记录（之后会跳转到 Fingerprint 控制面板）；否则，用户或获授权的 DNS 服务提供商工具会添加记录。仅当子域名处于 active 状态时才配置应用。验证后，请使用 get_subdomain 检查状态；遇到速率限制错误时，请遵循 retry_after。不提供子域名删除功能。

可用资源

• fingerprint://events/{event_id} — 返回给定事件 ID 对应的完整事件数据。
• fingerprint://schemas/event — 描述事件输出结构的 JSON Schema。
• fingerprint://schemas/environment — 环境对象的 JSON Schema。
• fingerprint://schemas/api-key — API 密钥对象的 JSON Schema。

技能

技能工具会从 GitHub 读取 Fingerprint skills repo，并将每个文件缓存一小时。在无法访问外部网络的部署中，传入 WithSkillsRepo("", "") 可禁用这些工具。

许可证

MIT