forcepointDSC-mcp

MCP server for the documented Forcepoint Data Security Cloud | SSE configuration APIs.

This repository keeps the original secure skeleton shape but is now specific to Forcepoint:

• Forcepoint user and group configuration APIs are exposed as dedicated MCP tools.

• Forcepoint upstream credentials are stored per user in Vault.

• Forcepoint connection defaults are stored per user in Postgres with default-user fallback.

• MCP HTTP access tokens are stored in Vault in a shared multi-user token index.

• Mutating tools honor MCP_ADMIN_AUTH_KEY when it is configured.

Coverage

The implementation covers all Forcepoint configuration endpoints documented in the referenced admin guide pages:

• User create or update

• User deactivate

• User reactivate

• User delete

• User read via v2

• User read via v2.1

• Group create or rename

• Group delete

• Group add members

• Group remove members

• Group list

• Group read with paging and status filtering

Source documentation:

• REST API index: https://help.forcepoint.com/fpone/sse_admin/prod/guid-aad2ad06-3314-41db-adc5-58e0a8c81baa.html

• Config API authentication: https://help.forcepoint.com/fpone/sse_admin/prod/oxy_ex-1/deployment_guide/guid-d35197e0-5924-4838-af15-6298cf9e7b50.html

• Basic auth guidance: https://help.forcepoint.com/fpone/sse_admin/prod/oxy_ex-1/deployment_guide/guid-6b3ba150-bd7d-4ec1-a8fb-7bb0a5f0719e.html

• User API details: https://help.forcepoint.com/fpone/sse_admin/prod/oxy_ex-1/deployment_guide/guid-a6f5d794-1d63-4cd7-afce-59858e71daf1.html

• Group API details: https://help.forcepoint.com/fpone/sse_admin/prod/oxy_ex-1/deployment_guide/guid-deb6dc8f-ec0c-423e-a8d5-b3589d02b858.html

Related MCP server: DelineaMCP

Architecture

Runtime flow:

1. src/index.js boots stdio mode.

2. src/http/index.js boots HTTP mode.

3. src/runtime/createAppServices.js creates Postgres, Vault, Forcepoint client, and HTTP token verifiers.

4. src/services/targetService.js resolves user-scoped Forcepoint config and credentials, then issues Forcepoint API calls.

5. src/mcp/server.js registers Forcepoint tools, admin-key gates, query suggestions, and multi-user token management.

6. src/http/server.js exposes MCP over HTTP with auth, rate limiting, and access logging.

Persistence model:

• Vault stores Forcepoint API credentials per user at APP_NAME/users/<user>/forcepoint/auth.

• Vault stores MCP HTTP bearer tokens in a multi-user token index at MCP_HTTP_VAULT_TOKEN_INDEX_PATH.

• Postgres stores connection config in APP_NAME_config keyed by (user_id, key).

Tool Surface

All tool responses use this envelope:

{
  "ok": true,
  "status": 200,
  "data": {}
}

Mutating tools return 401 if MCP_ADMIN_AUTH_KEY is configured and authorizationKey is missing or invalid.

The richest machine-readable tool documentation is returned by forcepoint_query_suggestion, which includes:

• When each tool should and should not be used

• Risk class and whether the tool is read-only or mutating

• Required permissions and prerequisites

• User-scope and environment-selection behavior

• Parameter constraints

• Expected response shapes

• Common failure conditions

• Recommended prerequisite and follow-up tools

• Safety warnings

• Valid invocation examples

Discovery And Runtime

Forcepoint Config And Credentials

MCP HTTP Access Tokens

Forcepoint User And Group APIs

OpenAPI Inventory

Generate the documented endpoint inventory artifact with:

npm run generate:endpoint-inventory

Generated output:

• artifacts/generated/forcepoint-openapi-endpoint-inventory.json

The artifact is built from the canonical endpoint catalog in src/services/forcepointCatalog.js.

Environment

Important variables:

• APP_NAME: naming root for Vault paths and Postgres table name

• MCP_ADMIN_AUTH_KEY: optional admin key enforced for all mutating tools

• MCP_CONFIG_DEFAULT_USER_ID: default user scope when userId is omitted

• FORCEPOINT_DEFAULT_BASE_URL: Forcepoint portal base URL fallback

• FORCEPOINT_DEFAULT_TIMEOUT_MS: Forcepoint request timeout fallback

• FORCEPOINT_DEFAULT_USER_API_VERSION: default user read API version, v2 or v2.1

• FORCEPOINT_CONFIG_BASE_URL_KEY: Postgres key for per-user base URL

• FORCEPOINT_CONFIG_TIMEOUT_MS_KEY: Postgres key for per-user timeout

• FORCEPOINT_CONFIG_USER_API_VERSION_KEY: Postgres key for per-user user-read API version

• FORCEPOINT_CONFIG_TENANT_KEY: Postgres key for per-user tenant context

• FORCEPOINT_CONFIG_ACCOUNT_KEY: Postgres key for per-user account context

• FORCEPOINT_VAULT_USER_AUTH_SECRET_SUFFIX: Vault suffix for per-user Forcepoint auth secrets

• MCP_HTTP_VAULT_TOKEN_INDEX_PATH: shared multi-user Vault index for MCP HTTP bearer tokens

See .env.example for the full list.

Running

Local development with bundled Postgres and Vault:

docker compose up -d
npm ci
npm run generate:endpoint-inventory
npm test

Stdio mode:

npm run start:stdio

HTTP mode:

npm run start:http

HTTP endpoint: http://127.0.0.1:3000/mcp

External Services Mode

Use docker-compose.external.yml when Vault and Postgres already exist outside this repo.

Required environment variables include:

• POSTGRES_HOST

• POSTGRES_PORT

• POSTGRES_DB

• POSTGRES_USER

• POSTGRES_PASSWORD

• VAULT_ADDR

• VAULT_TOKEN

This mode starts only the application container and preserves the same user-scoped Postgres/Vault behavior, including tenant/account context for multiple tenants.

Testing

Run all tests with:

npm test

The test suite covers:

• Forcepoint tool registration and auth gating

• HTTP transport authentication behavior

• Vault token-index helpers for multi-user MCP access tokens

• Generated-doc and external-deployment documentation expectations

License

MIT. See LICENSE.