<p align="center">
    <a href="https://fingerprint.com">
        <picture>
            <source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
            <source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
            <img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
        </picture>
    </a>
</p>

# Fingerprint MCP Server

## Features

- Run locally, or use the managed instance at https://mcp.fpjs.io/mcp (in Claude, add it from the [connectors directory](https://claude.ai/customize/connectors))
- **Event tools**: Retrieve and search identification and Automation Intelligence (edge) events with full smart signal data
- **Management tools**: Manage workspace environments, API keys and custom subdomains
- **Skills tools**: Serve the [Fingerprint skills](https://github.com/fingerprintjs/skills) (integration guides, proxy setup, Smart Signals) to clients that cannot fetch them themselves
- Supports both **stdio** and **streamable-http** transports
- Optional HTTPS with TLS certificates
- OAuth2 login supported
- **Public mode** for multi-tenant deployments (API keys passed via JWT bearer token)
- **Tool filtering** to control which tools are exposed
- Configurable via environment variables or CLI flags
- Docker support for easy deployment

## Installation

### From Source

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

### Build Locally

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

`make build` runs `go generate` (to download the OpenAPI spec and generate schema files under `internal/schema/`) and then builds the binary.

## Configuration

The server can be configured via CLI flags or environment variables:

| CLI Flag                     | Environment Variable             | Default                          | Description                                                              |
|------------------------------|----------------------------------|----------------------------------|--------------------------------------------------------------------------|
| `--serverapikey`             | `FINGERPRINT_SERVER_API_KEY`     |                                  | Fingerprint Server API key (private mode)                                |
| `--serverapiurl`             | `FINGERPRINT_SERVER_API_URL`     | api.fpjs.io                      | Custom Server API URL (omit to use default)                              |
| `--managementapikey`         | `FINGERPRINT_MANAGEMENT_API_KEY` |                                  | Fingerprint Management API key (private mode)                            |
| `--managementapiurl`         | `FINGERPRINT_MANAGEMENT_API_URL` | management-api.fpjs.io           | Custom Management API URL (omit to use default)                          |
| `--region`                   | `FINGERPRINT_REGION`             | `us`                             | API region: `us`, `eu`, or `ap` (private mode)                           |
| `--transport`                | `MCP_TRANSPORT`                  | `stdio`                          | Transport: `stdio` or `streamable-http`                                  |
| `--port`                     | `MCP_PORT`                       | `8080`                           | Port for HTTP/HTTPS server                                               |
| `--tlscert`                  | `MCP_TLS_CERT`                   |                                  | Path to TLS certificate file                                             |
| `--tlskey`                   | `MCP_TLS_KEY`                    |                                  | Path to TLS private key file                                             |
| `--readonly`                 | `MCP_READ_ONLY`                  | `false`                          | Only expose read tools (shorthand for `--tools` with read-only tools)    |
| `--tools`                    | `MCP_TOOLS`                      |                                  | Comma-separated list of tool names to register (overrides `--readonly`)  |
| `--publicmode`               | `MCP_PUBLIC`                     | `false`                          | Public mode: extract API keys from JWT bearer tokens                     |
| `--authtoken`                | `MCP_AUTH_TOKEN`                 | (auto-generated in private mode) | Bearer token required to access the server (private mode)                |
| `--jwtpublickey`             | `FINGERPRINT_PUBLIC_KEY`         |                                  | PEM-encoded ES256 public key for verifying Fingerprint-issued JWT tokens |
| `--oauthresource`            | `OAUTH_RESOURCE`                 |                                  | URL of this server (for OAuth metadata)                                  |
| `--oauthauthorizationserver` | `OAUTH_AUTH_SERVER`              |                                  | URL of the OAuth authorization server                                    |
| `--jwksurl`                  | `JWKS_URL`                       |                                  | JWKS URL for JWT token verification in public mode                       |
| `--openaiappschallengetoken` | `OPENAI_APPS_CHALLENGE_TOKEN`    |                                  | Domain verification token served at `/.well-known/openai-apps-challenge` |

## Telemetry

This binary ships with telemetry disabled. There is no built-in analytics
backend and the default emitter is a no-op, so running the OSS binary
sends nothing to anyone.

The server exposes a hook (`analytics.Emitter` in the `analytics`
package) that fires on each MCP method. Embedders who want product
analytics register their own emitter by importing this package as a
library and calling `WithAnalytics(emitter)` when constructing the
server. Fingerprint's hosted build (`mcp.fpjs.io`) does this with an
Amplitude emitter, but that implementation lives in the private managed
repo, not here.

If you build your own emitter, the event shape is in
`analytics/analytics.go`. The middleware fires one `mcp_method_called`
event per MCP method, gated on a non-empty `subscription_id` (so pre-auth
methods and the private-mode auth path stay silent regardless). Calls that
go through `call_tool` or `call_write_tool` report the proxy as `tool_name`
and the tool it was asked to run as `target_tool`, also when the proxy
rejects the call (then `is_error` is true).

## Request inspection

Embedders can register a second hook (`requestinspect.Inspector` in the
`requestinspect` package) that receives HTTP request metadata — method,
URL, original headers, and TCP peer address — for every request to the
`/mcp` endpoint, useful for audit logging and traffic analysis. Register
it with `WithRequestInspector(inspector)` when constructing the server.
The OSS binary configures no inspector, so nothing is collected.

The full contract (timing, fail-open behavior, read-only fields, stdio)
is documented in `requestinspect/requestinspect.go`, the source of truth
for this hook. See `requestinspect/example_test.go` for a complete
embedder-side implementation skeleton (bounded queue, background
delivery, header redaction, graceful drain).

## Usage

### Private mode vs. Public mode

Private mode means the server runs with its API keys pre-configured (`FINGERPRINT_SERVER_API_KEY` and `FINGERPRINT_MANAGEMENT_API_KEY`). This mode is useful when you are running a local instance intended to be used within your organization: server automatically uses those specified in the config. In this mode, auth token (`MCP_AUTH_TOKEN`) is enforced to protect your instance of the MCP server from unauthenticated use.

Public mode is how https://mcp.fpjs.io/mcp is run. It is meant to be used in situations when a single instance can be used by different users from different organizations, each with their own API keys. In this mode, API keys are extracted from JWT access tokens that are issued by https://dashboard.fingerprint.com or by user following the OAuth2 flow.

### Stdio Transport (Default)

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

### Streamable HTTP Transport

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

The MCP endpoint will be available at `http://localhost:8080/mcp`.

### HTTPS

Provide TLS certificate and key files to enable HTTPS:

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

### Tool Filtering

By default, all tools are registered based on which API keys are configured. You can restrict which tools are exposed:

```bash
# 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
```

When `--tools` is set, it overrides `--readonly`.

## Docker

### Build the Image

```bash
docker build -t fingerprint-mcp-server .
```

### Run with Stdio Transport

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

### Run with Streamable HTTP Transport

```bash
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 Client Configuration

### Hosted endpoint (managed)

The managed instance at `https://mcp.fpjs.io/mcp` runs in public mode and authenticates each user via OAuth2. Nothing to run or configure.

**In Claude**, add it from the connectors directory rather than as a custom connector: open [Customize > Connectors](https://claude.ai/customize/connectors), choose **Browse connectors**, and search for Fingerprint. The same catalog serves claude.ai, Desktop, mobile and Claude Code, so this only has to be done once per account.

Adding it as a custom connector still works, but you have to name it yourself, and some characters in that name break tool discovery while the connector still reports as connected.

**In other clients**, point them at the URL directly:

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=Fingerprint&config=eyJ1cmwiOiJodHRwczovL21jcC5mcGpzLmlvL21jcCIsInRyYW5zcG9ydCI6InN0cmVhbWFibGUtaHR0cCJ9)

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

### Self-hosted

Add to your Cursor/Claude Desktop/etc configuration file (e.g. `claude_desktop_config.json`):

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

**Streamable HTTP Transport:**
```json
{
  "mcpServers": {
    "fingerprint": {
      "url": "https://url/mcp",
      "headers": {
        "Authorization": "Bearer <auth-token>"
      }
    }
  }
}
```

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

## Available Tools

Event tools require a Server API key. Management tools require a Management API key. `get_current_time` and the skills tools need no key. `get_skill` and `get_skill_file` are not in the MCP tool list: run them through `call_tool`. With `--tools`, allow-list `list_skills`, `get_skill`, `get_skill_file` and `call_tool` for the skills to work. Write tools (create/update/delete/verify/connect) are hidden when `--readonly` is set or excluded via `--tools`.

| Tool                 | Description                                                         |
|----------------------|---------------------------------------------------------------------|
| `get_current_time`   | Return the current date/time in UTC (and an optional IANA timezone) |
| `list_skills`        | List the Fingerprint skills by id and description                   |
| `get_skill`          | Return one skill's instructions and the files it refers to          |
| `get_skill_file`     | Return one file from a skill, such as a code snippet                |
| `get_event`          | Retrieve a specific event by ID (identification or edge)            |
| `search_events`      | Search events with filters (visitor, IP, smart signals, time range) |
| `list_environments`  | List workspace environments with pagination                         |
| `get_api_key`        | Get details of a specific API key                                   |
| `list_api_keys`      | List API keys with optional type/status/environment filters         |
| `create_environment` | Create a new workspace environment                                  |
| `update_environment` | Update an existing workspace environment                            |
| `delete_environment` | Delete a workspace environment                                      |
| `create_api_key`     | Create a new API key (public/secret/proxy)                          |
| `update_api_key`     | Update an existing API key                                          |
| `delete_api_key`     | Delete an API key (irreversible)                                    |
| `list_subdomains`    | List custom subdomains with pagination                             |
| `get_subdomain`      | Get a subdomain's status and DNS records                            |
| `create_subdomain`   | Register a hostname and return the required DNS records             |
| `verify_subdomain`   | Request one DNS check, then return the freshly read status          |
| `connect_subdomain`  | Get a Domain Connect link that adds the DNS records at the provider |

For custom subdomains, follow `fingerprint-proxy-integration` through the skills tools. Creation
does not add DNS records: when the provider supports Domain Connect, `connect_subdomain` returns a
link the user opens to add them with one approval (they land on the Fingerprint dashboard
afterwards); otherwise the user or an authorized DNS-provider tool adds them. Configure the app
only when the subdomain is `active`. Use `get_subdomain` for status checks after verifying;
respect `retry_after` on rate-limit errors. Subdomain deletion is not exposed.

## Available Resources

- **`fingerprint://events/{event_id}`** — Returns full event data for a given event ID.
- **`fingerprint://schemas/event`** — JSON Schema describing the event output structure.
- **`fingerprint://schemas/environment`** — JSON Schema for environment objects.
- **`fingerprint://schemas/api-key`** — JSON Schema for API key objects.

## Skills

The skills tools read the [Fingerprint skills repo](https://github.com/fingerprintjs/skills) from GitHub and cache each file for an hour. Pass `WithSkillsRepo("", "")` to disable them on a deployment with no egress.

## License

MIT