/
Documentation

Integration Tokens

Integration tokens let external tools — CLI, CI/CD pipelines, MCP clients, and scripts — talk to your Meldoc workspace.

Every tool that connects to Meldoc uses the same token type. You create tokens in workspace settings, choose what they can access, and pass them to whatever tool needs them.

Tip: connecting an AI assistant or setting up the CLI? Select Connect an app on the Integration Tokens page instead of creating a token by hand — the wizard picks the setup for your client and issues the token for you. See Getting Started with MCP.

Create a token

  1. Open Settings → Integration Tokens.
  2. Select Create token.
  3. Configure the token (see below).
  4. Select Create.
  5. Copy the secret immediately — it’s shown only once.

The token starts with the prefix mdc_.

Each token also gets an auto-generated Client ID (e.g. acme-readonly). Unlike the secret, the Client ID is not sensitive and stays visible on the token row. It’s used only when sharing the token as a Claude.ai or Claude Desktop custom connector for scoped access, paired with the mdc_ secret as the Client Secret.

Name

Enter a descriptive name that identifies the token’s purpose — for example, github-actions-prod, claude-desktop, or local-dev-john.

Scope

Workspace gives the token access to all projects (requires Pro plan). Selected Projects limits access to specific projects only.

Note: Workspace-level scope requires a Pro plan. On other plans, you can select a single project.

Permission Level

Permission Level API value Access
Read read View and search published documents
Write write Read (including drafts) + create and update documents
Write and Delete maintain Write + delete documents and manage project settings

Any workspace member can create a token. Write and Write and Delete require a Pro plan; on other plans only Read is available. At runtime, the token’s effective access is capped by your own permissions — a token can’t do more than you can.

Glossary write

Tokens with the Write or Write and Delete permission level don’t get glossary write access automatically. Enable the Glossary Write toggle in the create dialog if the token needs to create, update, or delete glossary terms.

The toggle appears only when the permission level is Write or higher and you have glossary edit permission.

Expiration

Never means the token doesn’t expire. Set date adds a specific expiration date and time. For short-term integrations or testing, setting an expiration is recommended.

Revoke a token

  1. Open Settings → Integration Tokens.
  2. Find the token in the list.
  3. Select the Revoke Token action on the token row.
  4. Confirm the action.

Keep in mind: Revoked tokens stop working immediately. This can’t be undone.

Tokens show one of three statuses: Active (valid and working), Revoked (manually revoked), or Expired (past expiration date). Use the status filter at the top to switch between views (it defaults to active tokens). Members see and revoke only the tokens they created; admins can also toggle between their own tokens and all workspace tokens, and revoke any of them.

Use a token

With the CLI

Pass the token via flag or environment variable:

meldoc init --project YOUR_PROJECT_ID --token YOUR_TOKEN
meldoc pull --token YOUR_TOKEN
meldoc push --token YOUR_TOKEN

Setting MELDOC_TOKEN as an environment variable is recommended — the CLI picks it up automatically:

export MELDOC_TOKEN=your_token_here
meldoc pull
meldoc push

As a Claude.ai or Claude Desktop custom connector

For Claude.ai and Claude Desktop, OAuth (browser login) is the usual way to connect — see Authentication. Use a token-backed connector when you need to hand out scoped access to people without a full Meldoc account, for example read-only access to specific documents for a wider team. The token doubles as the connector’s OAuth client — no separate registration needed:

  1. On the Integration Tokens page, select the token’s Add to Claude.ai action to copy the Server URL (https://api.meldoc.io/mcp), Client ID, and (right after creation) the secret.
  2. In Claude, open Settings → Connectors → Add custom connector.
  3. Paste the Server URL, then enter the Client ID and the mdc_ token as the Client Secret under Advanced / OAuth settings.
  4. Select Connect. Everyone using the connector gets the token’s exact scope and permission level; revoking the token disables it immediately.

With MCP clients

Use the token as a Bearer token in your MCP client configuration. See Authentication for setup instructions for Claude, Cursor, VS Code, and other clients.

With the REST API

Pass the token in the X-Cli-Secret header along with your project alias:

curl -H "X-Cli-Secret: YOUR_TOKEN" \
     -H "X-Project-Alias: your-project" \
     https://api.meldoc.io/api/v1/tree

See REST API for the full API guide.

Find your project ID

To use the CLI, you need your project ID. Open your project in Meldoc and select Settings (gear icon) — the Project ID field is at the top.

You can also find it in the browser URL: https://app.meldoc.io/w/workspace/documentation/PROJECT_ID/...

Security best practices

Use descriptive names so you can identify each token’s purpose at a glance. Create separate tokens for different environments — dev, CI, and production should each have their own. Limit scope to specific projects when full workspace access isn’t needed.

Rotate tokens periodically, especially after team changes. Never commit tokens to version control — use environment variables or your CI platform’s secret store. For CI/CD setup details, see CI/CD Integration.

If a token is compromised, revoke it immediately, create a replacement with the same configuration, and update your environment variables or CI/CD secrets.

What’s next?

Authentication — Set up authentication for MCP clients.

Meldoc CLI — CLI overview and workflows.

CI/CD Integration — Publish documentation automatically from CI/CD pipelines.