Connect your AI tools to Atomicwork using the Model Context Protocol (MCP). Query tickets, create incidents, and manage service requests directly from your preferred client.

Authentication

The Atomicwork MCP server uses API token authentication. You need a public API token from your Atomicwork account.

To generate your API token:

Navigate to Profile > Public API Tokens.
Click Generate Token.
Copy the token (format: aw_xxx). You will not be able to see it again.

Your API token grants access to Atomicwork data scoped to your account permissions. Treat it like a password. Do not share it publicly. If a token is ever exposed, revoke it immediately and generate a new one.

Setup and configuration

The MCP server endpoint is tenant-specific. For example, if your Atomicwork tenant is acme, your endpoint is https://acme.atomicwork.com/mcp.

Server URL: https://<your-tenant>.atomicwork.com/mcp
Transport: Streamable HTTP
Auth Header: Authorization: Bearer aw_xxx

Claude Code

Run the following command in your terminal, replacing acme with your tenant name and aw_xxx with your API token:

claude mcp add --transport http Atomicwork https://acme.atomicwork.com/mcp --header "Authorization: Bearer aw_xxx"

Claude Desktop

Claude Desktop only supports local stdio servers. To connect to Atomicwork, use the mcp-remote bridge, which runs locally and forwards calls to the HTTP endpoint.

Prerequisite: Node.js must be installed. You can check this with node --version.

Add the following to your claude_desktop_config.json file:

{ "mcpServers": { "Atomicwork": { "command": "npx", "args": [ "-y", "mcp-remote", "https://<your-tenant>.atomicwork.com/mcp", "--header", "Authorization: Bearer <your-token>" ] } } }

If you already have an MCP server block, append this section. Do not replace the entire block.

Fully quit Claude Desktop and relaunch it for the changes to take effect.

Codex

Add the following block at the end of your ~/.codex/config.toml file:

[mcp_servers.Atomicwork] url = "https://acme.atomicwork.com/mcp" http_headers = { "Authorization" = "Bearer aw_xxx" }

Cursor

Add the following to .cursor/mcp.json in your project root or global config:

{ "mcpServers": { "Atomicwork": { "type": "http", "url": "https://acme.atomicwork.com/mcp", "headers": { "Authorization": "Bearer aw_xxx" } } } }

VS Code (GitHub Copilot)

Add the following to .vscode/mcp.json in your workspace:

{ "servers": { "Atomicwork": { "type": "http", "url": "https://acme.atomicwork.com/mcp", "headers": { "Authorization": "Bearer aw_xxx" } } } }

Any other MCP client

The server works with any client that supports the Streamable HTTP transport. Configure it with:

Field	Value
Server URL	`https://<your-tenant>.atomicwork.com/mcp`
Transport	Streamable HTTP
Auth header	`Authorization: Bearer aw_xxx`

If the client only accepts local stdio servers, use the mcp-remote wrapper from the Claude Desktop section above — the same pattern works for any stdio-only client.

Available tools

Once connected, your AI agent has access to several capabilities including:

Category	Tools
Tickets and requests	Search, view, create, update, and move requests across all types — general requests, incidents, problems, and service requests. Read and add notes and replies, manage links between tickets (parent/child, related, blocks), and initiate ad-hoc or policy-based approval lifecycles.
Service catalog	Browse the service catalog, search for catalog items in natural language ("I need a laptop"), and raise service requests against the right item with the right fields populated.
Assets and inventory	List and filter assets across all types — laptops, applications, monitors, servers, and any custom asset types — view full asset detail and activity history, and check the live health status of any application tracked in the inventory.
Users and workspaces	Look up the current user, search and view full profiles for any user, and discover the workspaces and user segments configured in the tenant.
Knowledge and search	Search internal knowledge — verified answers, topics, conversations — and run cross-entity searches that span requests, users, assets, and catalog items in one query.
Identity governance (IGA)	Search resources users can request access to, view access policies and entitlements, resolve the access a specific user already has, raise access requests, and validate business justifications.
Custom objects (beta)	Define, publish, and version custom object types (vendors, contracts, visas, anything tenant-specific); add fields to them; create, read, update, search, and delete instances; and link custom objects to requests and assets.

Example prompts

Try these prompts once connected:

Show me all P1 incidents opened in the last 24 hours.
What is the status of INC-4521? Who is assigned?
Create an incident: Zoom is down for the marketing team since 2pm.
Submit an access request for Figma for me.
What service requests are pending my approval?

Troubleshooting

If you encounter issues, check the following common solutions:

Claude Desktop: "Some MCP servers could not be loaded"

Claude Desktop rejected the config. The most common cause is a "type": "http" block — Claude Desktop only accepts local stdio servers in claude_desktop_config.json. Use the mcp-remote wrapper shown in Claude Desktop above.

Other things to check:

Invalid JSON in the config. A missing comma, trailing comma, or unquoted key will cause silent failure. Paste the file into jsonlint.com to validate.
You overwrote an existing mcpServers block. If you had other servers configured, they're gone. Merge the Atomicwork entry into the existing block instead of replacing it.

Claude Desktop: "Server disconnected" or red status

Open Settings → Developer → Atomicwork → View Logs, or tail the log directly on macOS:

bash

tail -n 100 ~/Library/Logs/Claude/mcp-server-Atomicwork.log

Common causes:

Placeholder token left in the config. Make sure aw_xxx is replaced with your real token.
Stray whitespace or newline in the token. Re-paste cleanly between the quotes.
Token expired or revoked. Generate a fresh one and update the config.
Node.js missing or not on PATH. Run node --version and npx --version. Install Node if either fails. Claude Desktop needs Node 18+; 20+ is recommended.
Wrong Node binary picked up. If you use nvm or have multiple Node installations, Claude Desktop may launch the wrong one. List them with which -a node. If the picked binary is too old or broken, replace "command": "npx" in your config with the absolute path — e.g. "command": "/Users/you/.nvm/versions/node/v22.15.0/bin/npx".
Forgot the -y flag in the npx args. Without it, npx prompts for confirmation interactively and the launch hangs. The snippet in Claude Desktop includes it — make sure yours does too.

Claude Desktop on Windows: `spawn npx ENOENT`

npx on Windows is a .cmd script, not a binary, and Node.js launched from a GUI app sometimes can't find it. Fixes, in order of effort:

Reinstall Node.js from nodejs.org using the official installer (not Homebrew, Scoop, or Chocolatey) and ensure "Add to PATH" is checked.
Reboot after install — Windows GUI apps don't pick up new PATH entries until next login.
If it still fails, replace "command": "npx" with the absolute path: "command": "C:\\Program Files\\nodejs\\npx.cmd". Note the double backslashes in JSON.

Codex: "Unable to load MCP status"

Codex couldn't parse config.toml. Run codex mcp list from a terminal to see the exact parse or connection error.