jumpcloud-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jumpcloud-mcp list all JumpCloud users"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_KEYStdio 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
authorizationKeywhenMCP_ADMIN_AUTH_KEYis configured.Full JumpCloud API coverage is supported via OpenAPI-driven discovery and execution.
Related MCP server: @godrix/argocd-mcp
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.yamlDirectory Insights API:
https://docs.jumpcloud.com/new/api/insights/directory/index.yaml
Coverage is exposed by:
jumpcloud_openapi_discoveryfor endpoint/operation discoveryjumpcloud_operation_invokefor operationId-driven executionjumpcloud_api_requestfor 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.jsonMarkdown summary:
docs/openapi-endpoint-inventory.md
Commands:
npm run inventory:generate
npm run inventory:checkinventory:check regenerates the artifact and fails if committed files are out of date.
CI workflow:
.github/workflows/openapi-inventory-check.ymlrunsnpm run inventory:checkon push and pull requests.
Architecture
Runtime flow:
src/index.jsstarts stdio MCP mode.src/http/index.jsstarts HTTP MCP mode.src/config/env.jsvalidates runtime configuration.src/services/vault.jsmanages persistent secrets.src/services/configStore.jsmanages persistent config in Postgres.src/services/targetService.jsloads OpenAPI and executes JumpCloud calls.src/mcp/server.jsregisters 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/userIdstored inuser_id)
Setup
Install dependencies:
npm installCopy and edit environment:
cp .env.example .envStart local infra:
docker compose up -d postgres vaultStart server:
npm run start:stdio
# or
npm run start:httpExternal Services Mode
Use docker-compose.external.yml when Vault and Postgres are managed externally.
Required env vars in this mode include:
POSTGRES_HOSTVAULT_ADDR
Start app-only stack:
docker compose -f docker-compose.external.yml up -dMCP 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:
intentstring optionaldomainenum optional:console|directory-insightsmethodstring optionalpathstring optionalincludeToolSchemasboolean optional
Response shape:
data.summarydata.recommendedOrderdata.suggestedOperationsdata.safetyChecksdata.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:
domainenum optional:console|directory-insightssearchstring optionallimitint optional (max 500)
Response shape:
data.endpoints[]data.countdata.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.
authorizationKeyrequired for mutating operations ifMCP_ADMIN_AUTH_KEYis set.Request must satisfy tenant/user policy guardrails when configured.
Environment behavior: operation domain inferred from OpenAPI metadata.
Parameters:
userIdoptional (defaults toMCP_CONFIG_DEFAULT_USER_ID)tokenIdoptional (defaults to active token)operationIdrequiredpathParamsoptional recordqueryoptional recordbodyoptional JSONheadersoptional recordauthorizationKeyoptional 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_requestfor 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.
authorizationKeyfor mutating methods (POST|PUT|PATCH|DELETE) when admin key is configured.Request must satisfy tenant/user policy guardrails when configured.
Environment behavior: routes via
domainto Console or Directory Insights base URL.Parameters:
userIdoptionaltokenIdoptionaldomainoptional:console|directory-insightsmethodrequiredpathrequiredqueryoptional objectbodyoptional JSONheadersoptional objectauthorizationKeyoptional 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_suggestionfor 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:
userIdoptionalincludeSensitiveoptional (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:
authorizationKeywhenMCP_ADMIN_AUTH_KEYis configured.
Environment behavior: writes to user Vault path and may initialize active token.
Parameters:
userIdoptionaltokenIdrequiredvaluerequiredtokenTypeoptional:apiKey|bearerheaderNameoptionaldescriptionoptionalauthorizationKeyoptional 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:
authorizationKeywhen admin key is configured.Environment behavior: updates active token pointer in Vault document.
Parameters:
userIdoptionaltokenIdrequiredauthorizationKeyoptional unless gated
Response shape:
data.userId,data.activeTokenIdCommon 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:
authorizationKeywhen admin key is configured.Environment behavior: deletes token and may reselect active token.
Parameters:
userIdoptionaltokenIdrequiredauthorizationKeyoptional unless gated
Response shape:
data.userId,data.activeTokenId,data.remainingTokenCountCommon 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>_configtable byuser_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:
authorizationKeywhen 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
authorizationKeywhenMCP_ADMIN_AUTH_KEYis 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
authorizationKeywhenMCP_ADMIN_AUTH_KEYis configured.Supports partial updates for:
allowMutationsallowedDomainsallowedMethodsallowedPathPrefixesenforceMutationOperationAllowListallowedOperationIds
Policy enforcement behavior:
If
allowedDomainsis non-empty, requests must match one of those domains.If
allowedMethodsis non-empty, requests must match one of those methods.If
allowedPathPrefixesis non-empty, request path must start with at least one prefix.If
allowMutations=false, mutating methods are denied.If
enforceMutationOperationAllowList=true, mutatingjumpcloud_operation_invokecalls must haveoperationIdinallowedOperationIds.
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 testHighlights:
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.
Available Tools
20 toolsjumpcloud_api_requestB
Generic JumpCloud request executor. Use for explicit domain/method/path calls with full endpoint coverage. Mutations require admin key if configured. Risk: variable.
Inputs: path (required), method (required), body, query, +6 more.
jumpcloud_config_deleteB
Mutating Postgres config delete. Use to remove obsolete non-secret settings. Destructive. Risk: high.
Inputs: key (required), userId, tenantId, authorizationKey.
jumpcloud_config_getA
Read-only Postgres config getter. Use to fetch one user-scoped configuration key. Risk: low.
Inputs: key (required), userId, tenantId.
jumpcloud_config_listA
Read-only Postgres config listing. Use to enumerate app/user scoped non-secret configuration values. Do not store secrets in config. Risk: low.
Inputs: prefix, userId, tenantId.
jumpcloud_config_setB
Mutating Postgres config setter. Use for non-secret runtime configuration. Do not store token values. Risk: medium.
Inputs: key (required), value, userId, tenantId, +1 more.
jumpcloud_connection_infoA
Read-only runtime metadata. Use when validating configured base URLs, OpenAPI source URLs, and persistence wiring. Do not use for API execution. Risk: low.
Inputs: no named parameters.
jumpcloud_health_checkA
Read-only health and credential check against JumpCloud using current user's active token. Use before large workflows. Risk: low.
Inputs: userId, tokenId, tenantId.
jumpcloud_openapi_discoveryA
Read-only OpenAPI discovery. Use to search operationId/method/path/tag metadata before invocation. Do not use as an execution tool. Risk: low.
Inputs: limit, domain, search.
jumpcloud_operation_invokeB
OpenAPI operation invoker. Use operationId+pathParams for high-fidelity execution with full API coverage. Mutating calls require admin key if configured. Risk: variable.
Inputs: operationId (required), body, query, userId, +5 more.
jumpcloud_query_suggestionB
Read-only planning helper. Use to choose safe tool order, discover likely operations, and retrieve tool usage schema details. Do not use for direct mutations. Risk: low.
Inputs: path, domain, intent, method, +1 more.
jumpcloud_scope_infoA
Read-only scope resolver. Use when you need the effective app/tenant/user scope and storage locations. Do not use for mutation. Risk: low.
Inputs: userId, tenantId.
jumpcloud_tenant_bootstrap_defaultsB
Mutating tenant/user baseline config initializer. Use to write recommended non-secret defaults for a scope. Risk: high.
Inputs: userId, defaults, tenantId, authorizationKey.
jumpcloud_tenant_listA
Read-only tenant discovery. Use to list tenant ids and optionally discover scoped users from Postgres and Vault token paths. Do not use for mutation. Risk: low.
Inputs: includeUsers.
jumpcloud_tenant_policy_getA
Read-only tenant/user policy reader. Use to inspect effective policy guardrails for a scope. Risk: medium.
Inputs: userId, tenantId.
jumpcloud_tenant_policy_setB
Mutating tenant/user policy writer. Use to update scoped policy guardrails for API execution. Risk: high.
Inputs: userId, tenantId, allowMutations, allowedDomains, +5 more.
jumpcloud_tenant_scope_validateB
Read-only tenant/user scope validation. Use to confirm token and config readiness before operational API calls. Risk: medium.
Inputs: userId, tenantId.
jumpcloud_user_token_deleteB
Mutating token deletion. Use when removing obsolete user tokens from Vault. Destructive. Risk: high.
Inputs: tokenId (required), userId, tenantId, authorizationKey.
jumpcloud_user_token_listA
Read-only token metadata listing. Use to inspect user-scoped token entries and active token selection. Do not use to rotate/update secrets. Risk: medium.
Inputs: userId, tenantId, includeSensitive.
jumpcloud_user_token_set_activeC
Mutating token selection. Use to change active token for a user. Do not use to create tokens. Risk: medium.
Inputs: tokenId (required), userId, tenantId, authorizationKey.
jumpcloud_user_token_upsertA
Mutating token create/update. Use to add or rotate JumpCloud user tokens in Vault. Do not use for read-only workflows. Risk: high.
Inputs: value (required), tokenId (required), userId, tenantId, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several read-only introspection tools (connection_info, scope_info, tenant_list, tenant_scope_validate, health_check, query_suggestion) have overlapping purposes and could be confused. The two API execution tools (operation_invoke and api_request) also serve similar functions with only subtle invocation differences.
Tool names mix noun endings (connection_info, openapi_discovery) with verb endings (tenant_list, config_get). The prefix 'jumpcloud_' is consistent, but the action part is not a uniform verb_noun pattern, making the naming style inconsistent.
At 20 tools, the server is on the heavier end of the typical range. While many tools serve distinct configuration and discovery purposes, the count could be trimmed by consolidating some overlapping introspection and execution tools.
The tool surface covers connection info, scope/tenant management, policies, token lifecycle, config storage, and API execution, leaving no major dead ends. Minor gaps exist around tenant mutation beyond bootstrap, but generic invocation fills most needs.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceRuntime MCP server that dynamically bridges any OpenAPI 3.x spec to MCP tools.9 npmMIT
- AlicenseBqualityCmaintenanceMCP server for Argo CD that provides multi-environment profiles, SSO or API key authentication, application search with cache, and REST API tools from the bundled OpenAPI catalog.26MIT
- AlicenseNot gradedqualityDmaintenanceConvert any OpenAPI spec into a secure MCP server with scoped auth, per-tool allow/deny policies, rate limiting, and a redacted audit trail.10 npmMIT
- FlicenseNot gradedqualityDmaintenanceA universal MCP server for registering internal, external, and OpenAPI-based APIs as MCP tools. It exposes them to MCP clients via Streamable HTTP and provides admin portal, RBAC/session auth, credential injection, and audit logging.-