TDX

You can interact with TeamDynamix data through an MCP server that wraps the TDx REST API, enabling natural language commands to manage tickets, assets, CMDB items, knowledge articles, people, projects, accounts, groups, and custom attributes. This server is designed to help you perform common IT service tasks faster with AI-assisted clients.

How to use

After you configure the MCP server, use your MCP client to issue natural language requests like creating a ticket, updating a CI, or searching the knowledge base. The server translates your natural language intents into TDx REST API calls, returning results and updates within your client. You can override the default application ID with an appId parameter when calling a specific tool if needed.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

Manual setup steps you can follow to install and run the MCP server locally:

npm install
npm run build

Configuration and start code

Add the MCP server configuration to your Claude Desktop config file. The following example shows how to run the server locally with Node and point Claude to the built index file. Be sure to replace the placeholder values with your actual TDx settings.

{
  "mcpServers": {
    "tdx": {
      "command": "node",
      "args": ["/path/to/TDX-MCP/dist/index.js"],
      "env": {
        "TDX_BASE_URL": "https://yourorg.teamdynamix.com/TDWebApi/api",
        "TDX_BEID": "your-beid-guid",
        "TDX_WEB_SERVICES_KEY": "your-web-services-key-guid",
        "TDX_APP_ID": "123"
      }
    }
  }
}

Authentication and security

The server uses admin token authentication to obtain access to the TDx API. Tokens are fetched lazily on the first tool call and are refreshed automatically after 23 hours, leaving a 1-hour buffer before the 24-hour expiry. Tokens are tied to a BEID and Web Services Key, not to individual user credentials, and can be revoked independently.

Environment variables

Configure the following environment variables to run the MCP server. These are the required values you must provide when starting the server.

TDX_BASE_URL=https://yourorg.teamdynamix.com/TDWebApi/api
TDX_BEID=your-beid-guid
TDX_WEB_SERVICES_KEY=your-web-services-key-guid
TDX_APP_ID=123

Usage examples

Once configured, you can ask Claude Desktop or Claude Code to perform actions such as: create a ticket, fetch a ticket and its comments, look up a person, search the knowledge base for VPN setup instructions, find assets in a department, or create a new software request ticket.

Project structure and tools overview

The MCP server exposes tools organized into domains such as Tickets, Assets, CMDB, Knowledge Base, People, Projects, Accounts, Groups, and Custom Attributes. Each tool corresponds to a specific REST endpoint or operation on a TDx instance. You can override the default appId for a given tool when needed.

Notes

Remember to restart Claude Desktop after configuring the MCP server so it can load the new server settings. If you encounter authentication expiry, allow the server to refresh the token automatically before subsequent tool calls.

Available tools

tdx-ticket-create

Create a new ticket

tdx-ticket-get

Get a ticket by ID

tdx-ticket-update

Full update of a ticket

tdx-ticket-patch

Partial update of a ticket

tdx-ticket-search

Search tickets with filters

tdx-ticket-feed-get

Get ticket comments/feed

tdx-ticket-feed-add

Add a comment to a ticket

tdx-ticket-add-asset

Link an asset to a ticket

tdx-ticket-add-contact

Add a contact to a ticket

tdx-asset-create

Create a new asset

tdx-asset-get

Get an asset by ID

tdx-asset-update

Full update of an asset

tdx-asset-patch

Partial update of an asset

tdx-asset-delete

Delete an asset

tdx-asset-search

Search assets with filters

tdx-asset-feed-add

Add a comment to an asset

tdx-cmdb-create

Create a new CI

tdx-cmdb-get

Get a CI by ID

tdx-cmdb-update

Full update of a CI

tdx-cmdb-delete

Delete a CI

tdx-cmdb-search

Search CIs with filters

tdx-cmdb-feed-add

Add a comment to a CI

tdx-cmdb-add-relationship

Add a relationship between CIs

tdx-kb-create

Create a KB article

tdx-kb-get

Get a KB article by ID

tdx-kb-update

Update a KB article

tdx-kb-delete

Delete a KB article

tdx-kb-search

Search KB articles

tdx-people-get

Get a person by UID

tdx-people-search

Search people with filters

tdx-people-lookup

Quick lookup by name/email/username

tdx-people-update

Update a person

tdx-project-create

Create a new project

tdx-project-get

Get a project by ID

tdx-project-update

Update a project

tdx-project-search

Search projects with filters

tdx-account-get

Get an account/department by ID

tdx-account-search

Search accounts/departments

tdx-group-get

Get a group by ID

tdx-group-search

Search groups

tdx-attributes-get

Get custom attribute definitions for a component type