/
Documentation

Authentication

Choose how your AI assistant authenticates with Meldoc. For Claude.ai and Claude Desktop, connect with a custom connector — OAuth (browser login) is recommended, with a scoped token available for restricted access. IDEs and CLI tools use an integration token. Device flow is available for headless environments.

Claude.ai & Claude Desktop (custom connector)

Connect Claude.ai (the web chat) and Claude Desktop with a custom connector pointed at https://api.meldoc.io/mcp.

Each person signs in with their own Meldoc account, so the connector carries their own permissions — nothing to create or share.

  1. In Claude, open Settings → Connectors → Add custom connector.
  2. Enter the Server URL https://api.meldoc.io/mcp and add the connector.
  3. Approve access on the Authorize Access page that opens.

No token needed; access is renewed silently afterward.

Optional: scoped access with a token (Client ID + Secret)

Use this when someone should not have a full Meldoc account but needs access to specific documents — for example, giving a wider team read-only access to a few projects. Create a scoped integration token and share it as a connector; everyone using it gets exactly the token’s access:

  • Server URL — https://api.meldoc.io/mcp
  • Client ID — the token’s auto-generated Client ID (e.g. acme-readonly), shown and copyable on the token row. Not secret.
  • Client Secret — the token’s mdc_… secret, shown only once at creation.

In Claude, open Settings → Connectors → Add custom connector, paste the Server URL, then enter the Client ID and Client Secret under Advanced / OAuth settings, and select Connect. The handshake is headless — no per-user login — and the connector is capped at the token’s scope and permission level. Revoking the token disables it immediately.

Tip: On the Integration Tokens page, each active token has an Add to Claude.ai action that opens a dialog with the Server URL, Client ID, and (right after creation) the secret, ready to copy.

See Getting Started with MCP for the full step-by-step.

Integration token (Bearer header)

For IDEs and CLI-based clients (Cursor, Claude Code, VS Code, Windsurf), create a token in the Meldoc web app and pass it to your MCP client as a Bearer header.

  1. Go to Settings → Integration Tokens → Create token.
  2. Copy the token (format: mdc_...).
  3. Add it to your Getting Started with MCP as a Bearer header (Authorization: Bearer mdc_...).

You can also pass the token as an environment variable:

export MELDOC_ACCESS_TOKEN=mdc_your_token_here

OAuth 2.1 (Claude Desktop via mcp-remote)

When using mcp-remote for Claude Desktop, authentication happens automatically. On first connect, a browser window opens for secure login — no token needed. mcp-remote handles token refresh in the background.

When an assistant is asked to connect again

An OAuth connection keeps itself alive in the background: it trades its credential for a fresh one, and each trade replaces the old one rather than re-using it. Presenting a credential that has already been traded in ends the session immediately, and every assistant on it has to connect again.

That is a safeguard rather than a fault — it is how a leaked credential stops being useful — and it has one everyday consequence. A copied or restored setup disconnects the original. Restoring a machine from a backup, cloning a container image with the credentials baked in, or running one saved session on two machines all present a credential that was already spent, and the connection drops. Reconnect the assistant and it works again.

Revoking a token in Settings → Integration Tokens cuts it at once, with no wait for anything to expire.

Device flow (CLI / headless)

For headless environments without a browser. Your AI assistant can call auth_login_instructions to get step-by-step instructions for completing device code authentication.

Check authentication status

Your AI assistant can call server_info to see whether it is authenticated and what it may do — it answers with the account, the permissions and the server’s capabilities. There is no separate authentication-status tool.

Token loading priority

When the MCP server receives a request, it checks for a token in this order:

  1. Environment variable — MELDOC_ACCESS_TOKEN set in your shell (highest priority).
  2. Saved session — credentials stored by OAuth or device-flow login, refreshed automatically when needed.
  3. Integration token variable — MELDOC_MCP_TOKEN.

Security best practices

  1. Never commit tokens — add credential files to .gitignore.
  2. Rotate tokens periodically — use Create token for a new one, then Revoke Token on the old row in Settings → Integration Tokens.
  3. Scope your tokens — Integration Tokens let you control exactly what each token can access.

What’s next?

MCP Tools Reference — Available MCP tools.

Troubleshooting — Fix authentication issues.

Integration Tokens — Create scoped tokens for integrations.