Skip to content
Documentation

Authentication

updated

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 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

For security, an OAuth session can’t be used from two places at once. If you restore a machine from a backup, clone a container with saved credentials, or reuse one session on two machines, the connection drops — just reconnect the assistant. Revoking a token on the Integration Tokens page cuts it off immediately.

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 on the Integration Tokens page.
  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.