/
Documentation

Troubleshooting

Issues you may encounter when using the Meldoc MCP server.

Authentication errors

AUTH_REQUIRED — token not found

The MCP server can’t authenticate your request.

  1. Check your token is set correctly in the Authorization header of your Getting Started with MCP.
  2. Go to Settings → Integration Tokens, switch the status filter from Active only to see all tokens, and check the token’s Status column reads Active (not Revoked or Expired).
  3. Ask your AI assistant to call server_info to check what it is authenticated as.
  4. For Claude Desktop with mcp-remote: restart the client to trigger re-authentication.

Invalid token — token expired or revoked

Your token is no longer valid.

Keep in mind: If you were recently removed from the workspace, your tokens stop working immediately — removing a member revokes every integration token they created. Ask a workspace admin to re-add you, then create a new token.

  1. Create a new token at Settings → Integration Tokens → Create token.
  2. Update your MCP config with the new token.
  3. Restart your client.

Workspace errors

WORKSPACE_REQUIRED — no workspace selected

You have multiple workspaces and none is selected.

  1. Ask your AI assistant to call list_workspaces, then to pass the one you want as workspaceAlias on its next call.
  2. Or add meldoc.config.yml to your project root:
   workspaceAlias: your-workspace-name

WORKSPACE_NOT_FOUND — wrong workspace alias

The workspaceAlias or workspaceId doesn’t match any workspace accessible to your token.

  1. Ask your AI assistant to call list_workspaces to see available aliases.
  2. Check for typos — workspace aliases are case-sensitive.

Note: WORKSPACE_NOT_FOUND means the alias didn’t match anything you can reach. WORKSPACE_ACCESS_DENIED means the workspace exists but your token isn’t a member.

AMBIGUOUS_DOC_ALIAS — alias exists in multiple projects

A tool was called with a doc alias that resolves in more than one project. Doc aliases are unique within a project, not across the workspace.

  1. Pass projectId or project_alias alongside docId to scope the lookup. The error message lists candidate project aliases.
  2. Or use the doc UUID — UUIDs are globally unique.

Connection issues

Client won’t connect

Your AI client can’t reach the MCP server.

  1. Check your config file — valid JSON, "type": "http" set, URL is https://api.meldoc.io/mcp.
  2. Restart your client completely.
  3. Test connectivity:
   curl https://api.meldoc.io/health

mcp-remote: browser window doesn’t open

The OAuth flow in mcp-remote doesn’t start.

  1. Verify Node.js 18+ is installed (node --version).
  2. Run npx mcp-remote https://api.meldoc.io/mcp manually to see errors.
  3. Or use a static token instead — see Authentication.

Get more help

  1. Ask your AI assistant to call server_info for what it is authenticated as.
  2. Enable debug logging with DEBUG=1.
  3. Open an issue at GitHub with error messages and steps to reproduce.