jumpcloud-mcp

MCP server for JumpCloud APIs with:

• Full API surface access through JumpCloud OpenAPI specs

• Multi-tenant and multi-user token management persisted in Vault

• Non-secret runtime configuration persisted in Postgres

• Mutating-tool guard using MCP_ADMIN_AUTH_KEY

• Stdio and HTTP transports

Solution Summary

This repository is adapted from skeleton-mcp into a JumpCloud-specific implementation.

Key design requirements implemented:

• Secrets are persisted in Vault only.

• Configuration is persisted in Postgres only.

• User tokens are scoped by tenant and user (app/tenants/:tenantId/users/:userId/jumpcloud/tokens).

• Tenant/user policy guardrails can restrict allowed domains, methods, paths, and mutating operationIds.

• Mutation tools can require authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

• Full JumpCloud API coverage is supported via OpenAPI-driven discovery and execution.

Related MCP server: @minamorl/openapi-mcp-bridge

JumpCloud Coverage Model

jumpcloud-mcp supports complete endpoint coverage by loading these OpenAPI specs at runtime:

• Console API: https://docs.jumpcloud.com/new/console/index.yaml

• Directory Insights API: https://docs.jumpcloud.com/new/api/insights/directory/index.yaml

Coverage is exposed by:

• jumpcloud_openapi_discovery for endpoint/operation discovery

• jumpcloud_operation_invoke for operationId-driven execution

• jumpcloud_api_request for explicit method/path execution

Endpoint Inventory Artifact

This repository can generate a deterministic endpoint inventory artifact for diffing API coverage changes:

• JSON inventory: docs/openapi-endpoint-inventory.json

• Markdown summary: docs/openapi-endpoint-inventory.md

Commands:

npm run inventory:generate
npm run inventory:check

inventory:check regenerates the artifact and fails if committed files are out of date.

CI workflow:

• .github/workflows/openapi-inventory-check.yml runs npm run inventory:check on push and pull requests.

Architecture

Runtime flow:

1. src/index.js starts stdio MCP mode.

2. src/http/index.js starts HTTP MCP mode.

3. src/config/env.js validates runtime configuration.

4. src/services/vault.js manages persistent secrets.

5. src/services/configStore.js manages persistent config in Postgres.

6. src/services/targetService.js loads OpenAPI and executes JumpCloud calls.

7. src/mcp/server.js registers tools, auth checks, and responses.

Persistence model:

• Secrets: Vault KV (secret/data/<app>/tenants/<tenant>/users/<user>/jumpcloud/tokens)

• Config: Postgres table (<app>_config) scoped by composite scope id (tenantId/userId stored in user_id)

Setup

1. Install dependencies:

npm install

2. Copy and edit environment:

cp .env.example .env

3. Start local infra:

docker compose up -d postgres vault

4. Start server:

npm run start:stdio
# or
npm run start:http

External Services Mode

Use docker-compose.external.yml when Vault and Postgres are managed externally.

Required env vars in this mode include:

• POSTGRES_HOST

• VAULT_ADDR

Start app-only stack:

docker compose -f docker-compose.external.yml up -d

MCP Tool Catalog

All tools return JSON in text content with shape:

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

Errors return isError=true and shape:

{
  "ok": false,
  "status": 401,
  "error": "Unauthorized: invalid authorizationKey for mutating API request"
}

jumpcloud_query_suggestion

• Use when: you need planning guidance, schema guidance, and recommended tool sequence.

• Do not use when: you already know the exact tool and operation.

• Access type: read-only.

• Risk: low.

• Required permissions: none.

• Environment behavior: reads active OpenAPI operation metadata from loaded specs.

• Parameters:

  • intent string optional

  • domain enum optional: console|directory-insights

  • method string optional

  • path string optional

  • includeToolSchemas boolean optional

• Response shape:

  • data.summary

  • data.recommendedOrder

  • data.suggestedOperations

  • data.safetyChecks

  • data.toolSchemas (unless disabled)

• Common failures: OpenAPI fetch/parse errors.

• Recommended prereq: jumpcloud_connection_info.

• Follow-up tools: jumpcloud_openapi_discovery, jumpcloud_operation_invoke, jumpcloud_api_request.

• Example:

{
  "name": "jumpcloud_query_suggestion",
  "arguments": {
    "intent": "list users then update one user",
    "domain": "console"
  }
}

jumpcloud_openapi_discovery

• Use when: you need schema discovery for operation IDs, methods, paths, tags, and domains.

• Do not use when: you are ready to execute and already know the operation.

• Access type: read-only.

• Risk: low.

• Required permissions: none.

• Environment behavior: returns operation metadata from OpenAPI cache.

• Parameters:

  • domain enum optional: console|directory-insights

  • search string optional

  • limit int optional (max 500)

• Response shape:

  • data.endpoints[]

  • data.count

  • data.totalDiscovered

• Common failures: OpenAPI fetch/parse errors.

• Recommended prereq: jumpcloud_connection_info.

• Follow-up tools: jumpcloud_operation_invoke, jumpcloud_api_request.

• Example:

{
  "name": "jumpcloud_openapi_discovery",
  "arguments": {
    "domain": "console",
    "search": "systemusers",
    "limit": 20
  }
}

jumpcloud_operation_invoke

• Use when: you have an operationId and want strict OpenAPI-based invocation.

• Do not use when: you only have raw method/path; use jumpcloud_api_request.

• Access type: read-only or mutating (depends on operation method).

• Risk: variable.

• Required permissions:

  • Active user token in Vault.

  • authorizationKey required for mutating operations if MCP_ADMIN_AUTH_KEY is set.

  • Request must satisfy tenant/user policy guardrails when configured.

• Environment behavior: operation domain inferred from OpenAPI metadata.

• Parameters:

  • userId optional (defaults to MCP_CONFIG_DEFAULT_USER_ID)

  • tokenId optional (defaults to active token)

  • operationId required

  • pathParams optional record

  • query optional record

  • body optional JSON

  • headers optional record

  • authorizationKey optional unless gated mutation

• Response shape:

  • data.domain, data.method, data.path, data.status, data.data

• Common failures:

  • Unknown operationId

  • Missing required path parameter

  • Missing/inactive token

  • JumpCloud API errors

• Recommended prereq: jumpcloud_openapi_discovery.

• Follow-up tools: jumpcloud_api_request for edge cases.

• Safety warning: high-impact on production identity/device state for mutating operations.

• Example:

{
  "name": "jumpcloud_operation_invoke",
  "arguments": {
    "userId": "team-a",
    "operationId": "systemusers_list",
    "query": {
      "limit": 10
    }
  }
}

jumpcloud_api_request

• Use when: you need explicit HTTP method/path execution with full API coverage.

• Do not use when: planning/discovery only.

• Access type: read-only or mutating.

• Risk: variable.

• Required permissions:

  • Active user token in Vault.

  • authorizationKey for mutating methods (POST|PUT|PATCH|DELETE) when admin key is configured.

  • Request must satisfy tenant/user policy guardrails when configured.

• Environment behavior: routes via domain to Console or Directory Insights base URL.

• Parameters:

  • userId optional

  • tokenId optional

  • domain optional: console|directory-insights

  • method required

  • path required

  • query optional object

  • body optional JSON

  • headers optional object

  • authorizationKey optional unless gated mutation

• Response shape:

  • data.domain, data.method, data.path, data.status, data.data

• Common failures: token missing, auth errors, timeout, invalid path, JumpCloud errors.

• Recommended prereq: jumpcloud_openapi_discovery.

• Follow-up tools: jumpcloud_query_suggestion for next step guidance.

• Safety warning: mutating calls can alter production directory state.

• Example:

{
  "name": "jumpcloud_api_request",
  "arguments": {
    "userId": "default",
    "domain": "console",
    "method": "GET",
    "path": "/api/systemusers"
  }
}

jumpcloud_user_token_list

• Use when: checking per-user token metadata and active selection.

• Do not use when: creating/updating/deleting tokens.

• Access type: read-only.

• Risk: medium.

• Required permissions: none.

• Environment behavior: reads Vault token document for selected user.

• Parameters:

  • userId optional

  • includeSensitive optional (actual values remain redacted unless sensitive output is enabled)

• Response shape:

  • data.userId, data.activeTokenId, data.tokens

• Common failures: Vault connectivity/read issues.

• Recommended prereq: jumpcloud_scope_info.

• Follow-up tools: jumpcloud_user_token_upsert, jumpcloud_user_token_set_active, jumpcloud_user_token_delete.

jumpcloud_user_token_upsert

• Use when: creating/updating a user-scoped JumpCloud token in Vault.

• Do not use when: read-only inspection.

• Access type: mutating.

• Risk: high.

• Required permissions:

  • authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

• Environment behavior: writes to user Vault path and may initialize active token.

• Parameters:

  • userId optional

  • tokenId required

  • value required

  • tokenType optional: apiKey|bearer

  • headerName optional

  • description optional

  • authorizationKey optional unless gated

• Response shape:

  • data.userId, data.tokenId, data.activeTokenId

• Common failures: Vault write failure, invalid payload.

• Recommended prereq: jumpcloud_scope_info.

• Follow-up tools: jumpcloud_user_token_set_active, jumpcloud_api_request.

jumpcloud_user_token_set_active

• Use when: switching active token for a user.

• Do not use when: creating token material.

• Access type: mutating.

• Risk: medium.

• Required permissions: authorizationKey when admin key is configured.

• Environment behavior: updates active token pointer in Vault document.

• Parameters:

  • userId optional

  • tokenId required

  • authorizationKey optional unless gated

• Response shape: data.userId, data.activeTokenId

• Common failures: unknown tokenId, Vault write failure.

jumpcloud_user_token_delete

• Use when: removing obsolete token entries.

• Do not use when: only deactivation is needed.

• Access type: mutating.

• Risk: high.

• Required permissions: authorizationKey when admin key is configured.

• Environment behavior: deletes token and may reselect active token.

• Parameters:

  • userId optional

  • tokenId required

  • authorizationKey optional unless gated

• Response shape: data.userId, data.activeTokenId, data.remainingTokenCount

• Common failures: Vault write failure.

• Safety warning: destructive operation.

jumpcloud_config_list / jumpcloud_config_get

• Use when: retrieving non-secret per-user Postgres config.

• Do not use when: storing secrets.

• Access type: read-only.

• Risk: low.

• Required permissions: none.

• Environment behavior: reads <app>_config table by user_id.

jumpcloud_config_set / jumpcloud_config_delete

• Use when: writing/deleting non-secret per-user configuration.

• Do not use when: storing token values or other sensitive secrets.

• Access type: mutating.

• Risk: medium/high.

• Required permissions: authorizationKey when admin key is configured.

• Environment behavior: writes/deletes rows in Postgres config table.

• Safety warning (jumpcloud_config_delete): destructive operation.

jumpcloud_tenant_list / jumpcloud_tenant_scope_validate / jumpcloud_tenant_bootstrap_defaults

• jumpcloud_tenant_list:

  • Read-only tenant discovery from Postgres scope ids.

  • Optional user discovery from both Postgres and Vault token paths.

• jumpcloud_tenant_scope_validate:

  • Read-only scope readiness checks for tenant/user.

  • Reports whether tokens/config are present and recommends next tools.

• jumpcloud_tenant_bootstrap_defaults:

  • Mutating baseline tenant/user config initializer.

  • Requires authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

  • Writes non-secret defaults only (never token secrets).

jumpcloud_tenant_policy_get / jumpcloud_tenant_policy_set

• jumpcloud_tenant_policy_get:

  • Read-only policy inspection for effective tenant/user guardrails.

  • Returns the current policy object for the requested scope.

• jumpcloud_tenant_policy_set:

  • Mutating policy update tool for tenant/user guardrails.

  • Requires authorizationKey when MCP_ADMIN_AUTH_KEY is configured.

  • Supports partial updates for:

    • allowMutations

    • allowedDomains

    • allowedMethods

    • allowedPathPrefixes

    • enforceMutationOperationAllowList

    • allowedOperationIds

Policy enforcement behavior:

• If allowedDomains is non-empty, requests must match one of those domains.

• If allowedMethods is non-empty, requests must match one of those methods.

• If allowedPathPrefixes is non-empty, request path must start with at least one prefix.

• If allowMutations=false, mutating methods are denied.

• If enforceMutationOperationAllowList=true, mutating jumpcloud_operation_invoke calls must have operationId in allowedOperationIds.

jumpcloud_connection_info / jumpcloud_scope_info / jumpcloud_health_check

• jumpcloud_connection_info: read-only server/runtime metadata.

• jumpcloud_scope_info: read-only effective app/user scope resolver.

• jumpcloud_health_check: read-only API connectivity/auth check using active user token.

HTTP Auth for MCP Endpoint

The MCP HTTP endpoint supports:

• Vault token index auth (MCP_HTTP_AUTH_MODE=token)

• OAuth2 introspection auth (MCP_HTTP_AUTH_MODE=oauth2)

• Dual acceptance (MCP_HTTP_AUTH_MODE=both)

Tests

Run:

npm test

Highlights:

• OpenAPI discovery and operation invocation tests

• Multi-tenant and multi-user token behavior tests

• Tenant discovery/scope validation/bootstrap tool tests

• Admin auth gating tests for mutating tools

• HTTP integration and Vault-related tests

License

MIT. See LICENSE.