AgentDesk MCP Server

MCP (Model Context Protocol) server for AgentDesk. Enables Claude Desktop, VS Code, and other MCP-compatible tools to interact with AgentDesk tickets, workflows, and portal administration.

Installation

npm install @noicework/agentdesk-mcp

Setup

Option A: OAuth Device Flow (Recommended)

No API key is required. Start the MCP server and approve the request in your browser:

npx @noicework/agentdesk-mcp

The CLI prints:

• a verification URL (opens AgentDesk approval page)
• a user code

Approve once and the refresh token is cached locally for future sessions.

Option B: API Key (Legacy)

Generate an API key from the AgentDesk portal:

1. Go to Settings > API Keys
2. Click Generate New Key
3. Select the scopes you need:
   • tickets:read / tickets:write - View and manage tickets
   • workflows:read / workflows:write - View and manage AI workflows
   • portals:read / portals:write - View and manage portals
   • users:read / users:write - View and manage users
   • admin:* - Full admin access
4. Optionally restrict to specific portals
5. Save the generated key securely - it's only shown once!

2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentdesk": {
      "command": "npx",
      "args": ["@noicework/agentdesk-mcp"],
      "env": {
        "AGENTDESK_URL": "https://portal.noice.net.au"
      }
    }
  }
}

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop to enable the AgentDesk tools.

Available Tools

Ticket Tools

| Tool | Description | Required Scope | |------|-------------|----------------| | list_tickets | List tickets with optional filtering | tickets:read | | get_ticket | Get ticket details and comments | tickets:read | | create_ticket | Create a new ticket | tickets:write | | add_comment | Add a comment to a ticket | tickets:write | | get_transitions | Get available status transitions | tickets:read + portal admin | | transition_ticket | Change ticket status | tickets:write + portal admin |

Workflow Tools

| Tool | Description | Required Scope | |------|-------------|----------------| | list_workflows | List AI workflows | workflows:read + portal admin | | get_workflow | Get workflow details and status | workflows:read + portal admin | | trigger_workflow | Start a workflow for a ticket | workflows:write + portal admin | | approve_workflow | Approve a pending workflow step | workflows:write + portal admin | | reject_workflow | Reject a pending workflow step | workflows:write + portal admin | | cancel_workflow | Cancel a running workflow | workflows:write + portal admin |

Portal Tools

| Tool | Description | Required Scope | |------|-------------|----------------| | list_portals | List accessible portals | portals:read | | get_portal | Get portal details | portals:read | | get_portal_settings | Get portal settings | portals:read + portal admin | | update_portal_settings | Update portal settings | portals:write + portal admin |

Admin Tools

| Tool | Description | Required Scope | |------|-------------|----------------| | list_portal_users | List users in a portal | users:read + portal admin | | invite_user | Invite a user to a portal | users:write + portal admin |

Resources

The server also provides MCP resources for context:

• agentdesk://context/user - Current user information and permissions
• agentdesk://context/portals - List of accessible portals

Role-Based Access Control

Tools are filtered based on your user role and API key scopes:

• org_member + customer: Basic ticket access (own tickets only)
• portal_admin: All tickets, workflows, portal settings, user management
• org_admin: Portal CRUD, organization-wide user management
• super_admin: Full platform access

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AGENTDESK_API_KEY | No | - | Legacy API key auth | | AGENTDESK_URL | No | https://portal.noice.net.au | Gateway API URL | | AGENTDESK_MCP_CLIENT_ID | No | agentdesk-mcp | OAuth client ID | | AGENTDESK_MCP_REFRESH_TOKEN | No | - | Pre-provisioned refresh token | | AGENTDESK_OAUTH_SCOPE | No | default scopes | Override requested scopes | | AGENTDESK_OAUTH_PORTAL_IDS | No | all accessible | Comma-separated portal UUID restrictions |

Example Usage

Once configured, you can ask Claude to help with:

• "Show me all open tickets"
• "Create a ticket for the login bug we discussed"
• "Add a comment to TKT-123 saying we're investigating"
• "What's the status of the workflow for TKT-456?"
• "Approve the pending code review for the authentication fix"
• "List all users in the support portal"

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
AGENTDESK_API_KEY=xxx npm start

License

MIT