# 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:

```json
{
  "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:

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

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

Stdio mode:

```bash
npm run start:stdio
```

HTTP mode:

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

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