---
title: "Authenticating an agent with undocsend"
description: "How an agent gets OAuth 2.1 credentials for the undocsend MCP server: discovery, client registration, PKCE, scopes, tokens and revocation."
canonical: "https://undocsend.com/auth.md"
last_updated: "2026-11-19"
---

# Authenticating an agent with undocsend

undocsend runs one remote MCP server, at `https://mcp.undocsend.com/mcp` (Streamable HTTP). It is for agents working for a workspace owner or admin: reading rooms, documents and visitor activity, building rooms and sharing them. Access uses **OAuth 2.1 authorization code with PKCE**, with a person approving each connection. That is the only supported method: there are no API keys, no client credentials grant, and no agent-identity or token-exchange endpoints.

(Investors and other dealroom visitors use a different, simpler path: a bearer token minted inside the room. See https://undocsend.com/llms.txt.)

## Discover

Start from the MCP endpoint or from the metadata documents:

- Protected resource metadata (RFC 9728): `https://mcp.undocsend.com/.well-known/oauth-protected-resource/mcp`. It names the resource (`https://mcp.undocsend.com/mcp`), the authorization server (`https://mcp.undocsend.com`), the scopes (`read`, `build`, `share`) and `bearer_methods_supported: ["header"]`.
- Authorization server metadata (RFC 8414): `https://mcp.undocsend.com/.well-known/oauth-authorization-server`. It lists `https://mcp.undocsend.com/oauth/authorize`, `/oauth/token`, `/oauth/register` and `/oauth/revoke`, `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported: ["none"]` and `client_id_metadata_document_supported: true`.
- An unauthenticated request to `https://mcp.undocsend.com/mcp` answers `401` with a `WWW-Authenticate: Bearer ...` challenge whose `resource_metadata` parameter is `https://mcp.undocsend.com/.well-known/oauth-protected-resource/mcp`.

## Pick a method

There is one: the authorization code flow with PKCE, as a **public client** (no client secret). Your client needs an id, which it gets in one of two ways:

1. **Dynamic client registration** (RFC 7591) at `/oauth/register`.
2. **Client ID metadata document**: use an `https` URL that serves your client metadata as the `client_id`, and skip registration.

## Register

`POST https://mcp.undocsend.com/oauth/register` with a JSON body:

    {
      "client_name": "My agent",
      "redirect_uris": ["http://127.0.0.1:33418/callback"],
      "token_endpoint_auth_method": "none",
      "grant_types": ["authorization_code", "refresh_token"],
      "response_types": ["code"]
    }

- Public clients only: `token_endpoint_auth_method` must be `none`.
- 1 to 10 redirect URIs. Any `https` URI; `http` only on `localhost`, `127.0.0.1` or `[::1]` (any port); plus Cursor's `cursor://anysphere.cursor-mcp/oauth/callback`. No fragments and no credentials in the URI. Redirect URIs are matched exactly, except the loopback port.
- The response (`201`) carries your `client_id`. A registered client that is never used is removed after 30 days, so register again if yours is rejected as unknown.
- Registration is rate limited per IP address; too many answer `429` with `temporarily_unavailable`.

With a client ID metadata document instead, the `client_id` is the document's `https` URL and its `redirect_uris` follow the same rules.

## Claim

Send the person to the authorization endpoint in a browser:

    https://mcp.undocsend.com/oauth/authorize?response_type=code
      &client_id=<client_id>
      &redirect_uri=<one of your redirect URIs>
      &code_challenge=<BASE64URL(SHA256(code_verifier))>
      &code_challenge_method=S256
      &scope=read%20build
      &state=<random>
      &resource=https%3A%2F%2Fmcp.undocsend.com%2Fmcp

- PKCE is required, `S256` only.
- Scopes are `read`, `build`, `share`. Unknown scopes are ignored. The consent screen always starts with `read` and `build` ticked and `share` unticked; asking for `share` only shows the person a note that your app wants it. The person approving makes the final choice.
- If you send `resource`, it must be `https://mcp.undocsend.com/mcp`.
- The person signs in to undocsend, then sees a consent screen naming your app and where access will be sent. They pick **one workspace** (only workspaces where they are an owner or admin and AI agents are allowed are listed) and the scopes. One connection is one workspace.
- The request is valid for 10 minutes and must be approved in the same browser it started in.
- On approval the browser is redirected to your `redirect_uri` with `code`, your `state` and `iss=https://mcp.undocsend.com`.
- An unknown `client_id` or a `redirect_uri` that isn't registered gets a JSON `400` and no redirect (there is nowhere safe to send it). Other request errors (for example a bad `resource` or a missing PKCE challenge) redirect back with `error`, `error_description`, `state` and `iss`. If the person clicks Cancel, the redirect carries `error=access_denied`. Problems on the consent screen itself (no eligible workspace, a sign-in step) are shown to the person there and don't redirect.

## Exchange

`POST https://mcp.undocsend.com/oauth/token` as `application/x-www-form-urlencoded`:

    grant_type=authorization_code
    &code=<code>
    &code_verifier=<code_verifier>
    &redirect_uri=<the same redirect URI>
    &client_id=<client_id>

The JSON response has `access_token` (prefixed `mcp_at_`), `token_type: "Bearer"`, `expires_in`, `refresh_token` (prefixed `mcp_rt_`) and the granted `scope`.

- Access tokens last 1 hour; refresh tokens 30 days.
- Refresh with `grant_type=refresh_token&refresh_token=<token>&client_id=<client_id>`. Every refresh returns a new pair. Reusing an old refresh token is treated as theft and disconnects the whole connection.

## Use the access_token

Send it on every MCP request to `https://mcp.undocsend.com/mcp`:

    Authorization: Bearer mcp_at_...

Tokens in the query string are not accepted. The token acts for the person who approved it, inside the one workspace they chose, limited to the scopes they ticked. Tool calls are recorded in the workspace's agent access log, which owners and admins can review.

## Errors

- OAuth endpoints answer errors as JSON: `{"error": "<code>", "error_description": "<text>"}`, using the standard codes (`invalid_request`, `invalid_client`, `invalid_grant`, `invalid_target`, `invalid_redirect_uri`, `invalid_client_metadata`, `unsupported_grant_type`, …).
- `401` from `https://mcp.undocsend.com/mcp`: the token is missing, expired or revoked. The `WWW-Authenticate` header points at the protected resource metadata; refresh, or run the flow again.
- `403` with `error="insufficient_scope"`: only for `share`. Calling a sharing tool on a connection without `share` returns this step-up challenge; run the authorization flow again asking for `share`, and the person decides whether to tick it. A tool that needs `read` or `build` on a connection without it returns an ordinary MCP tool error instead.
- `404` from `https://mcp.undocsend.com/mcp` or `/oauth/token`: AI agents are switched off for that workspace (or for the service). Nothing is revoked or used up; the same access token, refresh token or unexpired code works again once agents are switched back on.
- `429` with `temporarily_unavailable` from `/oauth/register` or `/oauth/token`: slow down and retry.
- The OAuth endpoints and metadata answer CORS requests from any origin, for browser-based clients.

## Revocation

- Your client: `POST https://mcp.undocsend.com/oauth/revoke` with `token=<access or refresh token>` (RFC 7009, form-encoded, no client authentication). It answers `200`, also for a token it doesn't know. Revoking a refresh token revokes the whole token family issued from that authorization code (every access and refresh token in it); revoking an access token ends only that token.
- The person: a workspace owner or admin can see every connected agent and disconnect it from the workspace settings, or turn AI agents off for the workspace. See https://undocsend.com/docs/agents/manage-and-security.md.

## More

- Connecting specific clients (Claude, ChatGPT, Cursor, any MCP client): https://undocsend.com/docs/agents/connect.md
- What agents can do and which permission each task needs: https://undocsend.com/docs/agents/what-agents-can-do.md
- Developer resources: https://undocsend.com/developers.md
