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

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

Tool	Use When	Risk	Notes
forcepoint_query_suggestion	You need planning, schema discovery, or tool sequencing help	low	Returns the full rich tool catalog for LLMs and operators
forcepoint_connection_info	You need server defaults, docs links, or persistence model details	low	Read-only
forcepoint_scope_info	You need exact Vault/Postgres paths for a user scope	low	Read-only
forcepoint_endpoint_inventory	You need documented endpoint coverage or the generated OpenAPI inventory	low	Read-only
forcepoint_health_check	You need a live credential/connectivity check	low	Uses the documented group-list endpoint

Forcepoint Config And Credentials

Tool	Use When	Risk	Notes
forcepoint_connection_config_get	You need resolved base URL, timeout, or preferred API version for a user	low	Read-only
forcepoint_connection_config_set	You need to persist base URL, timeout, or API version in Postgres	medium	Mutating
forcepoint_user_token_get	You need to confirm whether a Forcepoint credential is present	low	Read-only; values stay redacted
forcepoint_user_token_set	You need to store a bearer token or basic-auth credential in Vault	high	Mutating
forcepoint_user_token_delete	You need to remove a Forcepoint credential from Vault	high	Mutating

MCP HTTP Access Tokens

Tool	Use When	Risk	Notes
forcepoint_mcp_http_token_get	You need to list user-scoped MCP access tokens	low	Read-only
forcepoint_mcp_http_token_upsert	You need to issue or rotate an MCP bearer token	high	Mutating; optionally generates the token
forcepoint_mcp_http_token_revoke	You need to invalidate an MCP bearer token by tokenId	high	Mutating

Forcepoint User And Group APIs

Tool	Use When	Risk	Notes
forcepoint_user_create_or_update	Create or update a Forcepoint user	medium	Mutating
forcepoint_user_deactivate	Disable user access	high	Mutating
forcepoint_user_reactivate	Restore user access	medium	Mutating
forcepoint_user_delete	Delete a deactivated user	high	Mutating
forcepoint_user_get	Read a Forcepoint user via v2 or v2.1	low	Read-only
forcepoint_group_create_or_update	Create a group or rename a group	medium	Mutating
forcepoint_group_delete	Delete a group	high	Mutating
forcepoint_group_add_members	Add existing users to a group	medium	Mutating
forcepoint_group_remove_members	Remove users from a group	medium	Mutating
forcepoint_group_list	List groups	low	Read-only
forcepoint_group_get	Read one group with paging and status filters	low	Read-only
forcepoint_api_request	You need a documented endpoint that has no dedicated tool	variable	Use only after forcepoint_endpoint_inventory

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.