# forcepoint-mcp

`forcepoint-mcp` is a Node.js MCP server for the Forcepoint DLP 9.0 REST API.

It is built around three repository guarantees:

- Forcepoint connection configuration is persistent in Postgres.
- Forcepoint passwords, Forcepoint JWTs, and MCP HTTP bearer tokens are persistent in Vault.
- Multi-user and multi-tenant scope is explicit across tools, storage paths, and auth workflows.

## API coverage

Dedicated MCP tools cover the documented Forcepoint DLP 9.0 REST surface for:

- Authentication
  - `POST /dlp/rest/v1/auth/refresh-token`
  - `POST /dlp/rest/v1/auth/access-token`
- Incident management
  - `POST /dlp/rest/v1/incidents`
  - `POST /dlp/rest/v1/incidents/update`
- Policy management
  - `GET /dlp/rest/v1/policy/enabled-names`
  - `GET /dlp/rest/v1/policy/rules`
  - `GET /dlp/rest/v1/policy/rules/severity-action`
  - `GET /dlp/rest/v1/policy/rules/source-destination`
  - `GET /dlp/rest/v1/policy/rules/exceptions/all`
  - `GET /dlp/rest/v1/policy/rules/exceptions`
  - `POST /dlp/rest/v1/policy/rules`
  - `POST /dlp/rest/v1/policy/rules/severity-action`
  - `POST /dlp/rest/v1/policy/rules/source-destination`
  - `POST /dlp/rest/v1/policy/rules/exceptions`

The repository also exposes `forcepoint_api_request` for documented routes that do not yet deserve a more specialized tool surface.

## Tooling highlights

Discovery and planning:

- `forcepoint_schema_discovery`
- `forcepoint_query_suggestion`
- `forcepoint_connection_info`
- `forcepoint_scope_info`
- `forcepoint_health_check`

User profile and secret management:

- `forcepoint_set_user_connection`
- `forcepoint_get_user_connection`
- `forcepoint_set_user_password`
- `forcepoint_get_user_auth_state`
- `forcepoint_update_user_tokens`
- `forcepoint_issue_refresh_token`
- `forcepoint_issue_access_token`

MCP HTTP token administration:

- `forcepoint_create_mcp_user_token`
- `forcepoint_list_mcp_user_tokens`
- `forcepoint_revoke_mcp_user_token`

Forcepoint API operations:

- `forcepoint_get_incidents`
- `forcepoint_update_incidents`
- `forcepoint_list_enabled_policies`
- `forcepoint_get_policy_rules`
- `forcepoint_get_rule_severity_action`
- `forcepoint_get_source_destination`
- `forcepoint_list_rule_exceptions`
- `forcepoint_get_rule_exception_details`
- `forcepoint_post_policy_rules`
- `forcepoint_post_rule_severity_action`
- `forcepoint_post_source_destination`
- `forcepoint_post_rule_exceptions`
- `forcepoint_api_request`

All tools return JSON inside MCP text content. Mutating tools require `authorizationKey` whenever `MCP_ADMIN_AUTH_KEY` is configured.

Most tools accept an optional `accountId` argument so callers can explicitly target a tenant or account. When omitted, the server uses the default account scope.

## Storage model

Postgres stores configuration only, scoped by account and user:

- `forcepoint.connection`
  - `baseUrl`
  - `timeoutMs`
  - `username`
- Scope key format: `<account-id>:<user-id>:forcepoint.connection`

Vault stores secrets only, scoped by account and user:

- `forcepoint/accounts/<account-id>/users/<user-id>/forcepoint/auth`
  - `password`
  - `refreshToken`
  - `refreshTokenExpiresAt`
  - `accessToken`
  - `accessTokenExpiresAt`
- `forcepoint/http/auth/token-index`
  - multi-user MCP HTTP bearer token metadata and revocation state

## Local development

1. Copy `.env.example` to `.env`.
2. Start local Vault and Postgres:

```sh
docker compose up -d postgres vault
```

3. Install dependencies:

```sh
npm install
```

4. Start stdio mode:

```sh
npm run start:stdio
```

5. Start HTTP mode:

```sh
npm run start:http
```

6. Generate endpoint artifacts:

```sh
npm run generate:inventory
```

7. Run tests:

```sh
npm test
```

## External Services Mode

If Vault and Postgres are already managed outside this repository, use `docker-compose.external.yml` to run only the MCP application container.

Required external settings include:

- `POSTGRES_HOST`
- `POSTGRES_PORT`
- `POSTGRES_DB`
- `POSTGRES_USER`
- `POSTGRES_PASSWORD`
- `VAULT_ADDR`
- `VAULT_TOKEN` or Vault Agent runtime settings

This mode keeps the same storage model: config in Postgres, secrets in Vault.

## MCP registration

VS Code stdio example:

```json
{
  "servers": {
    "forcepoint-mcp": {
      "type": "stdio",
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/Users/lesterjohn/Documents/GitHub/forcepoint-mcp"
    }
  }
}
```

HTTP-capable clients can point to `http://127.0.0.1:3000/mcp` after `npm run start:http`.

## Generated artifacts

- `artifacts/forcepoint-endpoint-inventory.json`
- `artifacts/forcepoint-openapi.json`
- `scripts/generate-forcepoint-openapi.js`

## Safety notes

- Incident updates and all policy POST operations are high-risk.
- Forcepoint policy mutations can be hard to roll back. Back up Forcepoint before policy changes.
- `forcepoint_get_incidents` can return large payloads. The Forcepoint documentation notes a maximum of 10,000 incidents per response.
- `forcepoint_create_mcp_user_token` returns the raw bearer token once. Treat it as a secret.

## License

MIT. See `LICENSE`.