npm package: @jaketracey/agentdesk-mcp
Description: MCP server for AgentDesk - access tickets, workflows, and portal administration
Latest version: 0.2.0

# 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

```bash
npm install @jaketracey/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:

```bash
npx @jaketracey/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`

```json
{
  "mcpServers": {
    "agentdesk": {
      "command": "npx",
      "args": ["@jaketracey/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 |

### Asset Tools

| Tool | Description | Required Scope |
|------|-------------|-----------------|
| `list_assets` | List monitored assets for a portal | `portals:read` + portal admin |
| `get_asset` | Get details for one asset | `portals:read` + portal admin |
| `check_asset_status` | Trigger a manual status check for an asset | `portals:write` + portal admin |
| `add_asset` | Add a monitored asset | `portals:write` + portal admin |
| `update_asset` | Update asset configuration | `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

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
AGENTDESK_API_KEY=xxx npm start
```

## License

MIT