Source: https://atomicwork.docs.pageloop.ai/mcp-tools/introduction

# Introduction

## Atomicwork MCP Tools

Work with Atomicwork's AI workforce and IT service management platform from any MCP-compatible client, such as Claude Code, Cursor, VS Code, or OpenAI Codex. The Atomicwork MCP (Model Context Protocol) server gives AI agents and LLM-powered tools access to the same tickets, assets, custom objects, access requests, and AI Coworkers that people work with in Atomicwork. Every call runs with the permissions of the user whose token it uses.

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.
- **Discover AI Coworkers** — list AI Coworkers and inspect their versions and skills.
- **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

Every request to the Atomicwork MCP server must include a bearer token in the `Authorization` header:

```
Authorization: Bearer aw_xxx
```

Tool calls run with the identity and permissions of the user the token belongs to. To generate a token, click your profile icon, then select **Public API token**. To add the token to your MCP client, see [Connect your client](/mcp-tools/connect-your-client/overview). Claude Code and Codex can also connect with OAuth instead of a token.

## 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 Coworkers**        | Browse AI Coworkers, their version history, and skills                            |
| **Identity Governance** | Access request flows — resource search, policy lookup, entitlement resolution     |
| **Knowledge & Search**  | Knowledge base search, catalog search, and app health monitoring                  |

## Key Concepts

### Dynamic Field Resolution

All entity IDs vary by tenant. Never hardcode numeric IDs — always fetch them dynamically:

- **Requests:** `getFormFieldEntities` and `getFormFieldOptions`
- **Custom objects:** `customObjectGetFieldEntities` and `customObjectGetFieldOptions`
- **Assets:** `listAssetFilterFields` for filter attributes, and `getAssetTypeFormFields` for create and update fields

### Filter vs. Payload Values

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

- **Filters**: dropdown, user, and entity-reference filters take numeric IDs, not labels — passing a label returns a 400 error. Get IDs from the lookup tools listed above.
- **Payloads**: Choice fields use string `value` or `label`; user fields use numeric IDs; dropdowns use string option values