How do I use TDX MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TDX MCP Server Find all high priority tickets assigned to me" 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.

TDX MCP Server

A Model Context Protocol (MCP) server that wraps the TeamDynamix (TDX) REST API, enabling AI-assisted IT service management through Claude Desktop, Claude Code, and other MCP clients.

This server exposes 41 tools across 9 domains — tickets, assets, CMDB, knowledge base, people, projects, accounts, groups, and custom attributes — allowing natural language interaction with your TDX instance.

Quick Start

macOS

Double-click setup-mac.command
Enter your BEID, Web Services Key, and App ID when prompted
Restart Claude Desktop

Windows

Double-click setup-windows.bat
Enter your BEID, Web Services Key, and App ID when prompted
Restart Claude Desktop

Manual Setup

npm install
npm run build

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "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

This server uses TDX admin token authentication (POST /auth/loginadmin) with a BEID and Web Services Key — not username/password. These are API-specific service account keys that are:

Not tied to SSO or any user's credentials
Generated in TDAdmin > Organization Details > API Settings
Revocable independently without affecting user accounts
Accessible to any admin with the "Add BE Administrators" permission

Tokens are fetched lazily on the first tool call and auto-refreshed after 23 hours (1-hour buffer before the 24-hour TDX expiry).

Environment Variables

Variable	Required	Description
`TDX_BASE_URL`	Yes	TDX Web API base URL (e.g. `https://yourorg.teamdynamix.com/TDWebApi/api`)
`TDX_BEID`	Yes	Admin BEID from TDAdmin
`TDX_WEB_SERVICES_KEY`	Yes	Web Services Key from TDAdmin
`TDX_APP_ID`	Yes	Default TDX application ID (integer)

Tools (41)

All tools that operate within an application accept an optional appId parameter to override the default from TDX_APP_ID.

Tickets (9 tools)

Tool	Method	Endpoint	Description
`tdx-ticket-create`	POST	`/{appId}/tickets`	Create a new ticket
`tdx-ticket-get`	GET	`/{appId}/tickets/{id}`	Get a ticket by ID
`tdx-ticket-update`	POST	`/{appId}/tickets/{id}`	Full update of a ticket
`tdx-ticket-patch`	PATCH	`/{appId}/tickets/{id}`	Partial update of a ticket
`tdx-ticket-search`	POST	`/{appId}/tickets/search`	Search tickets with filters
`tdx-ticket-feed-get`	GET	`/{appId}/tickets/{id}/feed`	Get ticket comments/feed
`tdx-ticket-feed-add`	POST	`/{appId}/tickets/{id}/feed`	Add a comment to a ticket
`tdx-ticket-add-asset`	POST	`/{appId}/tickets/{id}/assets/{assetId}`	Link an asset to a ticket
`tdx-ticket-add-contact`	POST	`/{appId}/tickets/{id}/contacts/{uid}`	Add a contact to a ticket

Assets (7 tools)

Tool	Method	Endpoint	Description
`tdx-asset-create`	POST	`/{appId}/assets`	Create a new asset
`tdx-asset-get`	GET	`/{appId}/assets/{id}`	Get an asset by ID
`tdx-asset-update`	POST	`/{appId}/assets/{id}`	Full update of an asset
`tdx-asset-patch`	PATCH	`/{appId}/assets/{id}`	Partial update of an asset
`tdx-asset-delete`	DELETE	`/{appId}/assets/{id}`	Delete an asset
`tdx-asset-search`	POST	`/{appId}/assets/search`	Search assets with filters
`tdx-asset-feed-add`	POST	`/{appId}/assets/{id}/feed`	Add a comment to an asset

CMDB / Configuration Items (7 tools)

Tool	Method	Endpoint	Description
`tdx-cmdb-create`	POST	`/{appId}/cmdb`	Create a new CI
`tdx-cmdb-get`	GET	`/{appId}/cmdb/{id}`	Get a CI by ID
`tdx-cmdb-update`	PUT	`/{appId}/cmdb/{id}`	Full update of a CI
`tdx-cmdb-delete`	DELETE	`/{appId}/cmdb/{id}`	Delete a CI
`tdx-cmdb-search`	POST	`/{appId}/cmdb/search`	Search CIs with filters
`tdx-cmdb-feed-add`	POST	`/{appId}/cmdb/{id}/feed`	Add a comment to a CI
`tdx-cmdb-add-relationship`	PUT	`/{appId}/cmdb/{id}/relationships`	Add a relationship between CIs

Knowledge Base (5 tools)

Tool	Method	Endpoint	Description
`tdx-kb-create`	POST	`/{appId}/knowledgebase`	Create a KB article
`tdx-kb-get`	GET	`/{appId}/knowledgebase/{id}`	Get a KB article by ID
`tdx-kb-update`	PUT	`/{appId}/knowledgebase/{id}`	Update a KB article
`tdx-kb-delete`	DELETE	`/{appId}/knowledgebase/{id}`	Delete a KB article
`tdx-kb-search`	POST	`/{appId}/knowledgebase/search`	Search KB articles

People (4 tools)

These tools do not require an appId.

Tool	Method	Endpoint	Description
`tdx-people-get`	GET	`/people/{uid}`	Get a person by UID
`tdx-people-search`	POST	`/people/search`	Search people with filters
`tdx-people-lookup`	GET	`/people/lookup`	Quick lookup by name/email/username
`tdx-people-update`	POST	`/people/{uid}`	Update a person

Projects (4 tools)

These tools do not require an appId.

Tool	Method	Endpoint	Description
`tdx-project-create`	POST	`/projects`	Create a new project
`tdx-project-get`	GET	`/projects/{id}`	Get a project by ID
`tdx-project-update`	POST	`/projects/{id}`	Update a project
`tdx-project-search`	POST	`/projects/search`	Search projects with filters

Accounts (2 tools)

Tool	Method	Endpoint	Description
`tdx-account-get`	GET	`/accounts/{id}`	Get an account/department by ID
`tdx-account-search`	POST	`/accounts/search`	Search accounts/departments

Groups (2 tools)

Tool	Method	Endpoint	Description
`tdx-group-get`	GET	`/groups/{id}`	Get a group by ID
`tdx-group-search`	POST	`/groups/search`	Search groups

Custom Attributes (1 tool)

Tool	Method	Endpoint	Description
`tdx-attributes-get`	GET	`/attributes/custom`	Get custom attribute definitions for a component type

Common componentId values for tdx-attributes-get: 9 = Ticket, 27 = Asset, 63 = CI, 39 = KB Article, 2 = Project.

Example Usage

Once configured, you can use natural language in Claude Desktop or Claude Code:

"Search for open tickets assigned to me"
"Get ticket #12345 and show me the comments"
"Look up john.doe@example.com in TDX"
"Search the knowledge base for VPN setup instructions"
"Find all assets in the IT department"
"Create a ticket for a new software request"

TDX API Documentation

Project Structure

TDX-MCP/
  package.json
  tsconfig.json
  .env.example
  setup-mac.command        # macOS setup wizard
  setup-windows.bat        # Windows setup launcher
  setup-windows.ps1        # Windows setup wizard
  src/
    index.ts               # Entry point
    config.ts              # Environment variable loading
    auth.ts                # Admin token auth with auto-refresh
    tdx-client.ts          # Shared HTTP client
    tools/
      tickets.ts           # 9 ticket tools
      assets.ts            # 7 asset tools
      cmdb.ts              # 7 CMDB/CI tools
      kb.ts                # 5 knowledge base tools
      people.ts            # 4 people tools
      projects.ts          # 4 project tools
      accounts.ts          # 2 account tools
      groups.ts            # 2 group tools
      attributes.ts        # 1 custom attributes tool

Created by University of Montana IT with Claude