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., "@DEX_MCP Show me devices that haven't checked in for 7 days"
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.
An MCP (Model Context Protocol) server that exposes the 1E Platform Consumer API as 92 callable tools for any MCP-compatible LLM client (Claude Desktop, Cursor, etc.).
Controller | Tools |
ApplicableOperations | Get by type ID, Get by type name, Add, Delete |
Approvals | Approve instruction/scheduled/persistent (×3), CanApprove checks (×3), Pending notifications (×4) |
AuditLogs | Search, Add entries |
Authentication | 2FA token for instruction, 2FA token for scheduled instruction |
CachedUserGroupMemberships | Get, Add, Delete, Get groups for user, Add groups for user, Remove groups for user, Get users in group |
CachedUsers | List, Get by ID, Add, Update, Delete |
Certificates | List IdP certs, Download cert, Set active cert, Verify cert |
Consumers | List, Get by ID, Get by name, Search, Add, Update, Delete, Delete many, Refresh cache |
CustomProperties | Get by type ID/name, Get by ID, Search, Add, Update, Delete, Delete many |
CustomPropertyTypes | List, Add |
Devices | List, Search, Get by FQDN, Get by Tachyon GUID, Get management groups by FQDN, Summary |
ManagementGroups (device groups) | List, Get by ID, Get by name, Search, Get contents, Get all devices |
InstructionDefinitions | List, Get by ID, Get by name, Search |
Instructions | Send, Send to device, Get by ID, Search, Get statistics (×2), Get responses (×2), Get responding devices, Get target list, Cancel, Rerun |
ScheduledInstructions | Create, Get by ID, Search, Update, Cancel, Delete |
PersistentInstructions | Create, Get by ID, Search, Cancel, Delete |
Related MCP server: Halo ITSM MCP Server
src/
├── index.ts # MCP server entry point (stdio + Streamable HTTP transports)
├── client.ts # HTTP client — auth (OAuth/JWT, bearer, API key), token cache, retries
└── tools.ts # All 92 tool definitions
package.json
tsconfig.jsonnpm installONE_E_BASE_URL is always required, e.g. https://your-tenant.1e.com/consumer. Pick one auth mode:
Mode | Variables | Notes |
1. OAuth / JWT Certificate Assertion (preferred, auto-rotating) |
| Signs a client-assertion JWT (RS256), exchanges it for a Tachyon token, caches it (5 min safety buffer before expiry) |
2. Static bearer token |
| Manual rotation |
3. API key |
| Sent as |
export ONE_E_BASE_URL=https://your-tenant.1e.com/consumer
export ONE_E_PRIVATE_KEY_FILE=/path/to/key.pem
export ONE_E_CERTIFICATE_FILE=/path/to/cert.pem
export ONE_E_APPLICATION_ID=<azure-ad-app-id>
export ONE_E_CONSUMER_NAME=<tachyon-consumer-name># Development (stdio)
npm run dev
# Development (Streamable HTTP)
npm run dev:http
# Production
npm run build && npm startControlled by the TRANSPORT env var:
stdio (default) — for Claude Desktop / local MCP clients
http — Streamable HTTP on PORT (default 3000), endpoint /mcp, health check /health
HTTP-only env vars:
Variable | Description |
| HTTP port (default |
| Required. All |
| Allowed CORS origin (default |
| Set to |
Run in http mode to let several MCP clients connect to one running server instance. Two independent credential models:
Shared identity (default, ONE_E_CLIENT_SUPPLIED_KEY unset) — the server holds one 1E credential (any of the 3 auth modes above) and every connecting client uses it. MCP_AUTH_TOKEN gates access to your hosted server and is required in this mode.
Per-client identity (ONE_E_CLIENT_SUPPLIED_KEY=true) — each client supplies its own 1E credential on the request that opens its session, via an X-API-Key header (or an api_key/apiKey query parameter, for clients like Microsoft Copilot Studio whose "API key" auth option only supports query strings). The server builds a fresh, isolated 1E client for that session and uses it for every tool call the session makes — nobody's calls run under anyone else's 1E identity. Despite the header's name, the value is forwarded to 1E as a bearer token (X-Tachyon-Authenticate), not literally as X-API-Key — that's what worked empirically against a live tenant for Tachyon-issued session tokens (1E rejected the same token via X-API-Key with "No authentication token found," but accepted it via X-Tachyon-Authenticate). OAuth/JWT pass-through isn't supported — sending a private key per request is not something clients should do.
MCP_AUTH_TOKEN becomes optional in this mode: a valid X-API-Key satisfies the access gate on its own, since MCP clients that can only configure one credential (Copilot Studio included) can't also send a separate Authorization: Bearer header. If you do set MCP_AUTH_TOKEN, it's still accepted as an alternate path for clients that support two headers.
export ONE_E_BASE_URL=https://your-tenant.1e.com/consumer
export ONE_E_CLIENT_SUPPLIED_KEY=true
TRANSPORT=http npm startBy default every session hits the one tenant configured in ONE_E_BASE_URL. Set ONE_E_CLIENT_SUPPLIED_TENANT=true (requires ONE_E_CLIENT_SUPPLIED_KEY=true) to let each session pick its own tenant instead, via an X-1E-Base-URL header (or base_url/baseUrl query parameter):
export ONE_E_CLIENT_SUPPLIED_TENANT=trueArbitrary caller-supplied URLs are a real SSRF vector, so every one is validated before use: HTTPS-only, localhost rejected, and the hostname is DNS-resolved and rejected if it lands on a private, loopback, or link-local address (link-local — 169.254.0.0/16 — is where AWS/GCP/Azure serve instance credentials from, so this specifically blocks the classic cloud-metadata SSRF). This is a startup-configured, deliberate opt-in — it's refused to start if enabled without ONE_E_CLIENT_SUPPLIED_KEY, since arbitrary tenant selection must never be paired with the server's own shared credential (a caller could otherwise exfiltrate it by pointing "tenant" at a server they control).
Known limitation: the SSRF check resolves DNS once at session-creation time, not on every subsequent request — a sufficiently sophisticated DNS-rebinding attack could still slip through between the check and the actual request. Fine for testing/internal use; a production-grade multi-tenant deployment should additionally pin the resolved IP via a custom fetch dispatcher.
Header | Purpose | Required when |
| Alternate gate credential | Only if |
| Determines which 1E identity a session's calls run as, and satisfies the gate on its own |
|
| Determines which 1E tenant a session's calls hit | Optional even when |
Check your MCP client's docs for how it lets you set custom headers (or query parameters) on an HTTP connection.
By default all 92 tools are available. Set ONE_E_TOOL_ALLOWLIST to a comma-separated list of tool names to expose only a subset — everything else disappears from tools/list and is rejected if called anyway. Applies to both transports. Useful because an LLM pays a real token cost just to reason over the tool catalog on every turn, so a narrowly-scoped deployment should ship a narrow tool list, not all 92.
.env.example ships with a recommended scope for device health identification and remediation — find devices → find the right health-check/remediation instruction → run it → track it to completion:
ONE_E_TOOL_ALLOWLIST=devices_list,devices_search,devices_get_by_fqdn,devices_summary,management_groups_list,management_groups_get_contents,instruction_definitions_search,instruction_definitions_get_by_name,instructions_send,instructions_send_to_device,instructions_get_by_id,instructions_get_statistics,instructions_get_statistics_detail,instructions_get_responses,instructions_get_responses_aggregate,instructions_rerun,instructions_cancelThat's 17 tools instead of 92. It deliberately excludes approvals, persistent/scheduled instructions, and custom properties — add those back in if your remediation workflow needs an approval step, continuous (not just on-demand) monitoring, or health state tracked via custom properties rather than instruction responses.
Comment the line out (or unset the variable) to expose the full 92-tool catalog instead. An unknown tool name in the list fails the server at startup with a clear error, rather than silently having no effect.
Dockerfile + docker-compose.yml give you a two-stage build (compiles, then a slim runtime image running as a non-root user) with a health check.
cp .env.example .envEdit .env: set ONE_E_BASE_URL, pick one auth mode (see the table above), and set MCP_AUTH_TOKEN (unless you're using ONE_E_CLIENT_SUPPLIED_KEY=true, per Hosting for multiple MCP clients).
docker compose up -dThe server listens on PORT (default 3000) over plain HTTP — it doesn't terminate TLS itself. For anything beyond local use, put it behind whatever reverse proxy or tunnel you already use for TLS (nginx, Caddy, your cloud provider's load balancer, Tailscale Funnel, etc.), forwarding to that port.
curl http://localhost:3000/health
# {"status":"ok","sessions":0,"uptime":...}docker compose logs -f mcp # tail server logs
docker compose restart mcp # pick up new env vars (in-memory sessions are lost — see note below)
docker compose down # stop everything
docker compose up -d --build # rebuild after a code change and restartSessions live in memory and don't survive a restart — any MCP client with an open session will need to reconnect after one (it'll get a "session not found" until it does). Fine for a single instance; don't run multiple replicas of this service without externalizing session state first.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"1e-consumer": {
"command": "node",
"args": ["/absolute/path/to/1e-consumer-mcp/dist/index.js"],
"env": {
"ONE_E_BASE_URL": "https://your-tenant.1e.com/consumer",
"ONE_E_PRIVATE_KEY_FILE": "/absolute/path/to/key.pem",
"ONE_E_CERTIFICATE_FILE": "/absolute/path/to/cert.pem",
"ONE_E_APPLICATION_ID": "<azure-ad-app-id>",
"ONE_E_CONSUMER_NAME": "<tachyon-consumer-name>"
}
}
}
}Restart Claude Desktop and the tools appear automatically.
Copy this pattern into src/tools.ts:
{
name: "my_new_tool",
description: "What it does and what permissions it requires.",
inputSchema: {
type: "object",
properties: {
someParam: { type: "string", description: "..." },
},
required: ["someParam"],
},
async handler(args, client) {
const res = await client.get(`/MyEndpoint/${args.someParam}`);
return [{ type: "text", text: JSON.stringify(res.data, null, 2) }];
},
},Add a new Applicable Operation. Provide securableTypeId OR securableTypeName (not both). Names must be unique per type. Requires 'Security' permission on 'Security'.
Inputs: name (required), securableTypeId, securableTypeName.
Delete an Applicable Operation by ID. Fails if it has permissions attached. Requires 'Write' on 'Security'.
Inputs: id (required).
Returns all operations applicable to a securable type (by numeric ID). Requires 'Read' on 'Security'.
Inputs: securableTypeId (required).
Returns all operations applicable to a securable type (by name). Requires 'Read' on 'Security'.
Inputs: securableTypeName (required).
Approve or reject an Instruction. Users cannot approve their own instructions. Requires 'Approve' on the Instruction Definition.
Inputs: approved (required), instructionId (required), comment.
Approve or reject a Persistent Instruction (API v26.2+). Requires 'Approve' on the Instruction Definition.
Inputs: approved (required), persistentInstructionId (required), comment.
Approve or reject a Scheduled Instruction. Requires 'Approve' on the Instruction Definition.
Inputs: approved (required), scheduledInstructionId (required), comment.
Check whether the calling user can approve the given Instruction.
Inputs: instructionId (required).
Check whether the calling user can approve the given Persistent Instruction (API v26.2+).
Inputs: id (required).
Check whether the calling user can approve the given Scheduled Instruction.
Inputs: id (required).
Returns all pending approval requests (Instructions, Scheduled Instructions, Device Authorizations) the calling user can action.
Inputs: no named parameters.
Returns all Instructions pending approval that the calling user can approve.
Inputs: no named parameters.
Returns all Persistent Instructions pending approval that the calling user can approve (API v26.2+).
Inputs: no named parameters.
Returns all Scheduled Instructions pending approval that the calling user can approve.
Inputs: no named parameters.
Add one or more audit log entries (API v24.9+).
Inputs: entries (required).
Search audit logs. Filterable/sortable by: Component, Comment, CreatedTime, Message, UserName, DetailMessage. Requires 'Read' on 'Security'.
Inputs: skip, take, filter, sortBy, +1 more.
Submit a one-time token for Instruction Two-Factor Authentication. Only the instruction creator can call this.
Inputs: token (required), instructionId (required).
Submit a one-time token for Scheduled Instruction Two-Factor Authentication. Only the creator can call this.
Inputs: token (required), scheduledInstructionId (required).
Create a new user–group membership. Requires 'Write' on 'Security'.
Inputs: userId (required), groupId (required).
Batch-add a user to multiple groups (skips existing memberships). Requires 'Write' on 'Security'.
Inputs: userId (required), groupIds (required).
Remove the membership between a user and a group. Requires 'Delete' on 'Security'.
Inputs: userId (required), groupId (required).
Get the membership record for a specific user+group pair. Requires 'Read' on 'Security'.
Inputs: userId (required), groupId (required).
Get all group IDs a user belongs to. Requires 'Read' on 'Security'.
Inputs: userId (required).
Get all user IDs that are members of a specific group. Requires 'Read' on 'Security'.
Inputs: groupId (required).
Batch-remove a user from multiple groups (skips non-existent memberships). Requires 'Delete' on 'Security'.
Inputs: userId (required), groupIds (required).
Create a new cached user.
Inputs: username (required), email, displayName.
Delete a cached user by their integer ID.
Inputs: id (required).
Get a cached user by their integer ID.
Inputs: id (required).
List all cached users with optional skip/take pagination.
Inputs: skip, take.
Update a cached user. The body must include the user's ID.
Inputs: id (required), email, username, displayName.
Download a PEM-formatted IdP certificate by its thumbprint. Requires 'Read' on 'Infrastructure'.
Inputs: thumbprint (required).
List all available IdP certificates. Requires 'Read' on 'Infrastructure'.
Inputs: no named parameters.
Set the active IdP certificate by thumbprint. Requires 'Write' on 'Infrastructure'.
Inputs: thumbprint (required).
Verify whether a certificate (by thumbprint) can be used for IdP communication. Requires 'Write' on 'Infrastructure'.
Inputs: thumbprint (required).
Create a Consumer. Name must be alphanumeric+underscore only, unique. System consumers cannot be created. Requires 'Write' on 'Consumer'.
Inputs: name (required), maximumSimultaneousInFlightInstructions (required), isEnabled, applicationUrl, +4 more.
Delete a Consumer by ID. System consumers and those used by scheduled instructions cannot be deleted. Requires 'Write' on 'Consumer'.
Inputs: id (required).
Delete multiple Consumers by their IDs in one request. Requires 'Write' on 'Consumer'.
Inputs: ids (required).
Return a single Consumer by integer ID. Requires 'Read' on 'Consumer'.
Inputs: id (required).
Return a single Consumer by name (Base64-encoded automatically). Requires 'Read' on 'Consumer'.
Inputs: name (required).
Return all Consumers. Requires 'Read' on 'Consumer'.
Inputs: no named parameters.
Force a refresh of the internal Consumers cache.
Inputs: no named parameters.
Search Consumers. Filterable/sortable by: Name, Enabled, MaximumSimultaneousInstructions, OffloadTargetUrl, SystemConsumer. Requires 'Read' on 'Consumer'.
Inputs: skip, take, filter, sortBy, +1 more.
Update an existing Consumer. System consumers cannot be renamed or disabled. Requires 'Write' on 'Consumer'.
Inputs: id (required), name, isEnabled, applicationUrl, +5 more.
Create a Custom Property with optional values. Provide typeId OR typeName. Name: unique, ≤16 chars, no spaces. Values: unique, ≤32 chars each. Requires 'Write' on 'CustomProperty'.
Inputs: name (required), typeId, values, typeName.
Delete a single Custom Property by ID. Requires 'Write' on 'CustomProperty'.
Inputs: id (required).
Delete multiple Custom Properties by their IDs. Requires 'Write' on 'CustomProperty'.
Inputs: ids (required).
Return a single Custom Property by its ID.
Inputs: id (required).
Return all Custom Properties for a given type ID.
Inputs: typeId (required).
Return all Custom Properties for a given type name.
Inputs: typeName (required).
Search Custom Properties. Filterable/sortable by: Name, TypeName.
Inputs: skip, take, filter, sortBy, +1 more.
Update a Custom Property. values=null → unchanged; values=[] → removes all values. Requires 'Write' on 'CustomProperty'.
Inputs: id (required), name, typeId, values, +1 more.
Create a new Custom Property Type. Name: unique, ≤32 chars. System types cannot be created. Requires 'Write' on 'CustomProperty'.
Inputs: name (required), description.
Return all available Custom Property Types.
Inputs: no named parameters.
Get a single device by its fully-qualified domain name (FQDN), e.g. 'hostname.domain.com'.
Inputs: fqdn (required).
Get a single device by its Tachyon GUID (the unique identifier assigned by the 1E agent).
Inputs: guid (required).
Get the Management Groups that a device (identified by FQDN) belongs to.
Inputs: fqdn (required).
List all registered devices/agents known to the 1E platform.
Inputs: no named parameters.
Search devices with filter/sort/pagination. Body is a SearchPostModel: start (integer offset), pageSize, sort array. includeInherited=true includes devices from child management groups.
Inputs: sort, start, pageSize, includeInherited.
Get a summary count/status of devices matching an optional filter.
Inputs: start, pageSize.
Get a single Instruction Definition by its integer ID. Returns full schema including parameters needed.
Inputs: id (required).
Get an Instruction Definition by its exact name. Use this to find the definitionId and parameter schema before sending an instruction.
Inputs: name (required).
List all available Instruction Definitions (the templates that describe what instructions can be sent to devices).
Inputs: instructionType.
Search Instruction Definitions with filter/sort/pagination.
Inputs: sort, start, pageSize.
Cancel a running instruction. keepData=true retains any responses already collected; keepData=false deletes them.
Inputs: id (required), keepData.
Get an Instruction by its integer ID. Returns status, target info, parameters, and approval state.
Inputs: id (required).
Get the list of unique device FQDNs that have responded to an instruction.
Inputs: instructionId (required), local.
Get the actual responses/results from devices for an instruction. local=true returns data stored locally. Supports pagination via start/pageSize.
Inputs: instructionId (required), local, start, pageSize.
Get aggregated (grouped/counted) responses for an instruction — useful for survey-style instructions that return the same values from many devices.
Inputs: instructionId (required), local, pageSize.
Get execution statistics for an instruction: total devices targeted, how many responded, pending, errors.
Inputs: id (required).
Get detailed per-state statistics for an instruction.
Inputs: id (required).
Get the list of devices that were targeted by an instruction.
Inputs: instructionId (required).
Re-run a previously completed instruction with the same parameters and scope.
Inputs: instructionId (required).
Search Instructions with filter/sort/pagination.
Inputs: sort, start, pageSize.
Send an instruction to devices. Use definitionId or definitionName to identify the instruction template. Target devices via 'devices' (array of FQDNs like ['host.domain.com']) OR via 'scope' (management group expression). Parameters are passed as [{name, value}] pairs matching the definition's schema.
Inputs: devices, keepRaw, comments, parameters, +4 more.
Send an instruction directly to a single device identified by its Tachyon GUID. Simpler than instructions_send when you already know the device GUID.
Inputs: guid (required), comments, parameters, definitionId, +3 more.
Get all devices across all Management Groups.
Inputs: no named parameters.
Get a Management Group by integer ID.
Inputs: id (required).
Get a Management Group by name.
Inputs: name (required).
Get the devices that are members of a Management Group by its integer ID.
Inputs: id (required).
List all Management Groups (device groups). These are used to scope instructions to sets of devices.
Inputs: includeSystemGroups.
Search Management Groups with filter/sort/pagination.
Inputs: sort, start, pageSize.
Cancel a Persistent Instruction by integer ID.
Inputs: id (required).
Create a Persistent Instruction that continuously applies to all current and future devices matching a scope.
Inputs: devices, comments, parameters, definitionId, +3 more.
Delete a Persistent Instruction by integer ID.
Inputs: id (required).
Get a Persistent Instruction by integer ID.
Inputs: id (required).
Search Persistent Instructions with filter/sort/pagination.
Inputs: sort, start, pageSize.
Cancel a Scheduled Instruction by integer ID.
Inputs: id (required).
Schedule an instruction to run on a recurring schedule. Uses SQL Server Agent-style schedule fields: scheduleFreqType (1=once,4=daily,8=weekly,16=monthly), scheduleFreqInterval, scheduleActiveStartDate, scheduleActiveStartTime (HHMMSS as integer, e.g. 90000 = 09:00:00).
Inputs: devices, comments, parameters, definitionId, +12 more.
Delete a Scheduled Instruction by integer ID.
Inputs: id (required).
Get a Scheduled Instruction by integer ID.
Inputs: id (required).
Search Scheduled Instructions with filter/sort/pagination.
Inputs: sort, start, pageSize.
Update an existing Scheduled Instruction by ID.
Inputs: id (required), comments, parameters, scheduleEnabled, +4 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 92 tools
Tools are grouped under clear resource prefixes and mostly target distinct actions, so an agent can usually tell them apart. A few near-duplicates exist (list vs search, send vs send_to_device, get_by_id vs get_by_name) that could cause minor selection confusion, especially at this scale.
All tool names use the same lowercase snake_case resource_prefix + action pattern, such as consumers_add, scheduled_instructions_cancel, and management_groups_get_contents. The convention is highly predictable across all 92 tools.
92 tools is an extreme count for a single MCP server and will overwhelm an agent's tool-selection context, even though the underlying platform is broad. This falls squarely in the 50+ extreme mismatch range.
The surface covers core workflows well: send and retrieve instructions, schedule/persistent instructions, approvals, consumers, users, devices, management groups, custom properties, and audit logs. Minor gaps exist, such as no update for persistent instructions or custom property types and read-only management group operations, but agents can generally work around them.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Every Canopy public API operation as a tool, run as you after a browser sign-in or on an API key.
Single-connection MCP gateway discovering and executing 490+ verified MCP & A2A tools.
