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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# OAuth and scopes

> Use authorization code flow with PKCE and the mcp:tools scope.

Melso uses OAuth authorization code flow with **PKCE S256**. The public scope is **`mcp:tools`**. It grants access to the tools that the selected company and person permit; it does not bypass membership, plan or human-approval checks.

| Purpose | Production URL |
| - | - |
| Issuer | `https://melso.ai` |
| Authorization metadata | `https://melso.ai/.well-known/oauth-authorization-server` |
| Browser authorization | Use `authorization_endpoint` from authorization metadata. |
| Token exchange and refresh | `https://melso.ai/oauth/token` |
| Dynamic client registration | `https://melso.ai/oauth/register` |
| Revocation | `https://melso.ai/oauth/revoke` |
| Protected resource | `https://melso.ai/api/mcp` |

Fetch metadata instead of hardcoding the authorization endpoint in a client:

```bash theme={null}
curl --fail-with-body https://melso.ai/.well-known/oauth-authorization-server
```

Use the same protected-resource URL throughout discovery, authorization, token exchange and MCP calls. These examples use `https://melso.ai/api/mcp`; do not switch to an alias partway through the flow.

## Token exchange

A compatible MCP client normally handles registration, the browser redirect, PKCE, state validation, and token storage. Melso supports public PKCE clients with `token_endpoint_auth_method: none`: send `client_id` and omit `client_secret` on both exchange and refresh. A custom client sends form-encoded token requests.

The Bash example below requires Python 3 and an interactive terminal. Enter values from the authorization flow your client just completed; the redirect URI and verifier must match that flow. Prompts hide the values, form data reaches curl through standard input, and the token response is saved to a private temporary file. No secret is passed as a command argument or exported variable.

```bash theme={null}
(
set +x
set -euo pipefail
umask 077
token_file=$(mktemp "${TMPDIR:-/tmp}/melso-oauth.XXXXXX")
trap 'rm -f "$token_file"' ERR
python3 - <<'PYTHON' | curl --fail-with-body https://melso.ai/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-binary @- --output "$token_file"
import getpass
import warnings
from urllib.parse import urlencode

warnings.simplefilter("error", getpass.GetPassWarning)
fields = {"grant_type": "authorization_code", "resource": "https://melso.ai/api/mcp"}
for name in ("client_id", "code", "redirect_uri", "code_verifier"):
    value = getpass.getpass(f"{name}: ")
    if not value:
        raise SystemExit(f"{name} is required")
    fields[name] = value
print(urlencode(fields), end="")
PYTHON
printf 'Token response saved to %s\n' "$token_file"
)
```

Read `access_token` from that file for [the first MCP read](/mcp/connect#try-a-first-read). Import the access and refresh tokens into your client's secure storage, then remove the temporary file. Do not paste the response into a conversation or log it. The example prints only the file path.

## Refresh a connection

Use the same registered `client_id` and the latest `refresh_token`. Keep `resource=https://melso.ai/api/mcp` in refresh requests too. The server accepts an omitted resource; if supplied, it must be a supported Melso MCP resource URL. Omission does not select a different company or audience.

```bash theme={null}
(
set +x
set -euo pipefail
umask 077
token_file=$(mktemp "${TMPDIR:-/tmp}/melso-oauth.XXXXXX")
trap 'rm -f "$token_file"' ERR
python3 - <<'PYTHON' | curl --fail-with-body https://melso.ai/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-binary @- --output "$token_file"
import getpass
import warnings
from urllib.parse import urlencode

warnings.simplefilter("error", getpass.GetPassWarning)
fields = {"grant_type": "refresh_token", "resource": "https://melso.ai/api/mcp"}
for name in ("client_id", "refresh_token"):
    value = getpass.getpass(f"{name}: ")
    if not value:
        raise SystemExit(f"{name} is required")
    fields[name] = value
print(urlencode(fields), end="")
PYTHON
printf 'Token response saved to %s\n' "$token_file"
)
```

Refresh rotates both tokens. Store each newly returned token pair atomically, retire the old pair, and remove the temporary response file after import. Revocation accepts an access or refresh token; company membership is rechecked on calls. Never log access tokens, refresh tokens, authorization codes or the verifier.

Personal memory belongs to the person behind the OAuth grant. Run tokens and integration identities cannot read or write personal memory; see [Memories](/concepts/memories).

See the [protocol reference](/mcp/reference) for transport and company binding; the [OAuth endpoint reference](/api-reference/tags/oauth) owns request and response contracts.


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