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

TDX MCP Server

TDX MCP Server

Quick Start

macOS

Windows

Manual Setup

Authentication

Environment Variables

Tools (41)

Tickets (9 tools)

Assets (7 tools)

CMDB / Configuration Items (7 tools)

Knowledge Base (5 tools)

People (4 tools)

Projects (4 tools)

Accounts (2 tools)

Groups (2 tools)

Custom Attributes (1 tool)

Example Usage

TDX API Documentation

Project Structure

Latest Blog Posts

MCP directory API