MCP Setup

MCP (Model Context Protocol) allows external AI tools and applications to connect to your AgentDesk portal securely.

What is MCP?

MCP provides a standardised way for AI-powered tools to interact with your portal's ticket system. With MCP enabled, authorised external applications can read ticket information, post updates, and trigger workflows through a secure connection.

Enabling MCP access

Go to Admin > Settings > MCP Access.
Configure the MCP client settings for your organisation.
Save the settings.

Once enabled, authorised MCP clients can connect to your portal using the OAuth-based authentication flow.

How MCP authentication works

MCP uses OAuth for secure authentication. External applications must:

Be registered as an authorised MCP client
Authenticate through the OAuth flow
Receive a scoped access token

This ensures that only approved applications can access your portal data, and each application only has access to the data it needs.

Use cases

Use case	Description
AI assistants	Connect AI tools that can read and update tickets on behalf of your team
Automation tools	Allow external automation platforms to interact with your ticket workflows
Custom integrations	Build custom tools that connect to your portal through a standard protocol

API keys

API keys provide programmatic access to the AgentDesk API for scripts, integrations, and MCP clients.

Creating an API key

Go to Admin > Settings > MCP Access.
Click Create API Key.
Enter a name to identify the key.
Select one or more scopes to control what the key can access.
Optionally restrict the key to a specific portal.
Click Create. Copy the key immediately -- it is only shown once.

API keys use the format noice_sk_live_ followed by a unique token.

Scopes

Scope	What it allows
`tickets:read`	Read ticket details, comments, and attachments
`tickets:write`	Create and update tickets, add comments
`workflows:*`	Trigger and manage AI workflows
`portals:read`	Read portal configuration and user lists
`portals:write`	Update portal settings
`users:read`	Read user profiles and roles
`users:write`	Invite users and update roles

Portal restrictions

When creating a key, you can restrict it to a single portal. A restricted key can only access data within that portal. Keys without a portal restriction can access all portals in the organisation.

Revoking a key

To revoke an API key:

Go to Admin > Settings > MCP Access.
Find the key in the list and click Revoke.
Confirm the action.

Revoked keys stop working immediately. This cannot be undone.

Device flow authentication

For MCP clients running on devices without a browser (such as CLI tools or headless servers), AgentDesk supports the OAuth 2.0 device authorisation flow:

The MCP client requests a device code from AgentDesk.
The user is shown a URL and a code to enter.
The user opens the URL in a browser, signs in, and enters the code.
Once approved, the MCP client receives an access token.

This flow allows MCP clients to authenticate securely without handling user credentials directly.

Security

MCP connections are authenticated and scoped
All communication uses encrypted HTTPS
Access can be revoked at any time from the MCP settings page
Activity is logged for auditing