> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-test.atomicwork.com/llms.txt.
> For full documentation content, see https://developer-test.atomicwork.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-test.atomicwork.com/_mcp/server.

# Introduction

## Atomicwork MCP Tools

The Atomicwork MCP (Model Context Protocol) server exposes your service management platform to AI agents and LLM-powered tools. These endpoints power the Atomicwork AI Employee and can be consumed by any MCP-compatible client.

With the MCP tools, AI agents can:

* **Manage ITSM tickets** — create, update, search, and link requests, incidents, problems, and service requests.
* **Browse and manage assets** — list, filter, inspect, create, and update IT assets.
* **Work with custom objects** — discover object types, create instances, and manage custom fields.
* **Access identity governance** — search resources, resolve entitlements, and submit access requests.
* **Manage AI Employee agents** — create, configure, publish, and version AI agents.
* **Search knowledge** — query the organisation's knowledge base, service catalog, and app health status.
* **Execute workflows** — search and fire request automations (runbooks) on tickets.

## Authentication

MCP tools are accessed via the Atomicwork AI Employee runtime. Authentication is handled by the platform — agents inherit the identity and permissions of the AI Employee they belong to.

For direct MCP server access, include your API key in the `X-Api-Key` header:

```
X-Api-Key: <your-api-key>
```

## Tool Categories

| Category                | Description                                                                       |
| ----------------------- | --------------------------------------------------------------------------------- |
| **Tickets**             | Full lifecycle management for requests, incidents, problems, and service requests |
| **Links & Approvals**   | Relationship management and approval workflows between entities                   |
| **Users & Workspaces**  | User lookup, workspace listing, and service catalog browsing                      |
| **Assets**              | IT asset management — browse, filter, create, update, and track activity          |
| **Custom Objects**      | Tenant-defined entity types with configurable schemas and field management        |
| **AI Agents**           | AI Employee agent configuration, versioning, and tool catalog access              |
| **Identity Governance** | Access request flows — resource search, policy lookup, entitlement resolution     |
| **Knowledge & Search**  | Knowledge base search, catalog search, and app health monitoring                  |
| **Integrations**        | Credential management and authenticated HTTP request execution                    |

## Key Concepts

### Dynamic Field Resolution

All entity IDs vary by tenant. Never hardcode numeric IDs — always fetch them dynamically using `getFormFieldEntities` or `getFormFieldOptions`.

### Filter vs. Payload Values

Filter values (used in list/search operations) and create/update payload values follow different conventions:

* **Filters**: ENTITY\_REFERENCE fields use numeric `id` from `getFormFieldEntities`
* **Payloads**: Choice fields use string `value` or `label`; user fields use numeric IDs; dropdowns use string option values

### Pagination

Most list endpoints support offset-based pagination with `page` (1-indexed) and `page_size` parameters. Check `total_pages` in responses to determine if more pages are available.