> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protodesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to hosted MCP

> Connect an MCP client to your Protodesk workspace using browser-based OAuth.

## Connect your client

Add a remote MCP server with this URL:

```text theme={null}
https://api.protodesk.io/mcp
```

Choose **Streamable HTTP** and **OAuth** in a client that supports OAuth dynamic client registration and PKCE. Client setup labels vary. No client secret or local Protodesk adapter is required.

When the browser opens:

1. Sign in to Protodesk.
2. Check the client name and callback origin. Client names are self-declared.
3. Choose the workspace you want the client to access. You must be its owner or admin.
4. Review the requested permissions, remove any you do not need, and allow access.
5. Return to your client and call `workspace_context` to check the connected workspace.

Each connection is bound to one workspace and the person who approved it. Authorize a separate connection for another workspace. Existing workspace API keys can also authenticate using the `Authorization: Bearer …` header; never put credentials in the URL.

## Permissions

Without an explicit scope request, OAuth requests customer and conversation read access. A client lists only tools allowed by its approved permissions.

| Scope | Allows |
| - | - |
| `customers:read` | Read customers and their identities |
| `customers:write` | Create, update, and delete customers and identities |
| `conversations:read` | Read conversations, messages, taxonomy, and assignments |
| `conversations:write` | Create, update, assign, and resolve conversations |
| `messages:write` | Record messages through the public API |
| `messages:send` | Send customer replies and cancel pending delivery |
| `webhooks:manage` | Manage webhooks and inspect or test deliveries |

There are [30 operational tools](/mcp/hosted-tools), including `workspace_context`. Write tools execute changes immediately. They require `expectedWorkspaceId`; operations that support safe retries also require `idempotencyKey`. Confirm the workspace before writing and reuse the same arguments and key when reconciling an uncertain retry.

<Warning>
  `create_message` records a message. Use `send_message` with `messages:send` for customer delivery. A queued reply is not proof of delivery; inspect it with `get_message`.
</Warning>

## Manage or disconnect

Open **Settings → Connected clients** in the selected Protodesk workspace to see your connections and revoke access. Removing your owner or admin role also prevents that connection from being used.

Access tokens last 15 minutes. Clients refresh them automatically using rotating refresh tokens. Connections expire after 90 days. Revocation, repeated authorization-code use, or refresh-token reuse invalidates the connection.

## Client requirements

The server supports stateless Streamable HTTP with JSON responses. A 401 response advertises OAuth resource metadata. Clients must support:

* OAuth authorization code flow with PKCE S256.
* Dynamic registration at `https://api.protodesk.io/oauth/register`, with public client authentication (`none`).
* `resource=https://api.protodesk.io/mcp` on authorization and token requests.
* Exact HTTPS or literal loopback HTTP callback URLs (`127.0.0.1` or `[::1]`, including the registered port).
* Client-generated `state` checked on return.

Discovery is available at [resource metadata](https://api.protodesk.io/.well-known/oauth-protected-resource/mcp) and [authorization server metadata](https://api.protodesk.io/.well-known/oauth-authorization-server). Client ID Metadata Documents, wildcard callbacks, client secrets, and client-credentials grants are not supported.

## Current boundaries

OAuth covers operational customer, conversation, message, and webhook tools. Help Center authoring still requires an API key with its own authoring permissions and human review. See [Help Center setup](/mcp/setup).

Key management, realtime subscriptions, attachments, and AI endpoints are not MCP tools in this release. OAuth tokens cannot be used as REST API keys. Browser MCP connections from other origins are not supported; native and server clients normally omit the Origin header.

Requests are limited to 128 KiB, tool request bodies to 64 KiB, and responses to 2 MiB. Normal API permissions and rate limits still apply.

## Troubleshooting

* **The client cannot connect:** confirm it supports Streamable HTTP, dynamic registration, PKCE S256, and the resource parameter.
* **No eligible workspace:** sign in with a current owner or admin account.
* **A tool is missing:** reconnect with the needed scope and approve it explicitly.
* **Access stopped working:** check role changes, revoked access, connection expiry, or token reuse. Reconnect rather than reusing old refresh credentials.
* **A write timed out:** read the resource to reconcile its state. Do not repeat an uncertain write with a new idempotency key.

## Workspace identifiers

Use the exact `workspaceId` returned by `workspace_context` as `expectedWorkspaceId` on writes. The workspace address shown in General settings is a slug, not this internal ID. A mismatch is rejected before changing data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.