Skip to content
Documentation

Getting Started with MCP

updated

Connect your AI assistant to Meldoc in a few minutes — the connect wizard does the setup for you.

Fastest path: the connect wizard

The wizard picks the setup for your client and issues a token only where that setup needs one, when you ask for it. Nothing to copy by hand but one command — or one click.

  1. Open Integration Tokens in the sidebar.
  2. Select Connect an app.
  3. Choose Connect an AI assistant.
  4. Pick your client — Claude, Claude Code, Cursor, VS Code, Windsurf, Codex, or Other for any MCP client.
  5. Follow the steps shown for your client. You get either a one-click install button or a copy-ready command, with your workspace already filled in.

Claude and Claude Code sign in through your browser and need no token. Every other client, the Prefer a config file? route of any client and Use the API need one: select Issue a key for your client (or Issue an API key) and the wizard issues a read-only token for the whole workspace and fills it into the steps. Picking a client or opening a section never issues a token by itself, and one token serves every client you open on the same visit. Wizard tokens never expire — revoke the ones you no longer use on the Integration Tokens page.

The wizard detects the first successful request on its own and switches to Connected, so you’ll know it worked without leaving the page.

Connect wizard — pick your client

Keep in mind: The token is shown once. Meldoc stores only a hash of it, so if you lose the value, issue a new token — there is no way to reveal an old one.

Until a client connects, Needs you on the workspace Overview carries a setup line tracking it. It names the token you’re waiting on, and disappears the moment Meldoc sees a request. If this workspace will never use an AI client, close the line with ×; it stays closed for that workspace in that browser, and Integration Tokens still has Connect an app.

Everything below is the manual equivalent — use it when you’re scripting a setup or you prefer editing config by hand.

Manual setup: Cursor / Claude Code / VS Code / Windsurf

These clients support Streamable HTTP natively. Add this to your MCP config file:

{
  "mcpServers": {
    "meldoc": {
      "type": "http",
      "url": "https://api.meldoc.io/mcp?workspace=your-workspace",
      "headers": {
        "Authorization": "Bearer mdc_your_token_here"
      }
    }
  }
}

The ?workspace= parameter pins the connection to one workspace — recommended if your account belongs to more than one. See Choosing a workspace below.

Config file locations:

Client Config path
Cursor (project) .cursor/mcp.json
Cursor (global) ~/.cursor/mcp.json
Claude Code (project) .mcp.json
Claude Code (global) ~/.claude.json
VS Code .vscode/mcp.json
Windsurf .windsurf/mcp.json

Restart your client after saving.

Claude Desktop & Claude.ai

Both connect through a custom connector pointed at https://api.meldoc.io/mcp. Use OAuth if you can. Everyone signs in with their own Meldoc account, so there’s no token to pass around and each connector carries that person’s permissions.

  1. In Claude, open Settings → Connectors → Add custom connector.
  2. (Claude Desktop only) In Name, enter anything you like (e.g. “Meldoc”).
  3. In URL, enter https://api.meldoc.io/mcp.
  4. Select Add.
  5. On the Authorize Access page that opens, review the access scope and select Allow.

You’re ready to go once the consent page closes — no tokens or config files needed, and access renews silently afterward.

The connect wizard’s Claude option skips these five steps. It builds an install link that opens the Add custom connector dialog with the name and URL already filled in.

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

Use this to give people scoped access without a full Meldoc account — read-only access to a few documents for a wider team, say. Create an integration token with the right scope and share it as a connector. Everyone using it gets exactly the token’s access.

  1. Create a token at Integration Tokens → Create token. Copy the mdc_… secret — it’s shown only once. Each token also has an auto-generated Client ID (copyable on the token row).
  2. In Claude, open Settings → Connectors → Add custom connector.
  3. Server URL: https://api.meldoc.io/mcp.
  4. Under Advanced / OAuth settings, enter the Client ID and the mdc_… token as the Client Secret.
  5. Select Connect. No per-user login — everyone using the connector gets the token’s exact scope and permissions.

Note: Claude.ai won’t add two connectors with the same URL. To connect a second Meldoc workspace, point it at https://api.meldoc.io/mcp0 (and a third at /mcp1) — they are identical servers. Three is all there is: /mcp, /mcp0 and /mcp1. A fourth workspace has no slot to take, so use one connector and pass the workspace per call instead — see Getting Started with MCP.

Alternative: mcp-remote bridge

If custom connectors aren’t available, use mcp-remote as a bridge (requires Node.js 18+):

{
  "mcpServers": {
    "meldoc": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.meldoc.io/mcp"]
    }
  }
}

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

mcp-remote handles authentication automatically — on first connect it opens a browser window for login. No token needed.

To use a static token instead:

{
  "mcpServers": {
    "meldoc": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.meldoc.io/mcp", "--header", "Authorization:Bearer mdc_your_token_here"]
    }
  }
}

Restart Claude Desktop after editing.

Verify the connection

If you used the wizard, it flips to Connected on the first successful request. To check by hand, ask your assistant something that has to hit Meldoc:

“Search my Meldoc docs for the deployment runbook.”

If it responds with your workspace data, you’re good to go.

Legacy: npm proxy

For clients that don’t support Streamable HTTP or mcp-remote, the @meldocio/mcp-stdio-proxy npm package is available as a fallback (requires Node.js 18+):

npx @meldocio/mcp-stdio-proxy@latest install
npx @meldocio/mcp-stdio-proxy@latest auth login

See the package README for full usage.

What’s next?

Authentication — Token management and login methods.

MCP Tools Reference — See all available MCP tools.

Getting Started with MCP — Switch between workspaces.

Choosing a workspace

If your account belongs to several workspaces, pin one in the connector URL — https://api.meldoc.io/mcp?workspace=your-workspace — or in meldoc.config.yml in your project root:

workspaceAlias: your-workspace

Otherwise the server uses a token scoped to one workspace, a workspaceAlias passed in the tool call, the last workspace you used, or your only workspace. Without any of these, tool calls return WORKSPACE_REQUIRED. You can also just ask your assistant to “list my workspaces” or “use company-docs”.