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.

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.