/
Documentation

Workspace Management

If you have access to multiple workspaces, you need to tell the MCP server which one to use. Most of the time, this happens automatically.

How workspace selection works

The server picks a workspace in this order:

  1. Token scope — if you connected with an integration token scoped to one workspace, that workspace is used.
  2. Connection pin — a workspace named in the connector URL as ?workspace=your-workspace (or an X-Meldoc-Workspace header, for clients that let you set one).
  3. Explicit parameter — workspaceAlias or workspaceId passed in a tool call.
  4. Project config — meldoc.config.yml in your project root or git repository.
  5. Cached default — the last workspace you used explicitly.
  6. Only workspace — if you have just one, it’s selected automatically.

Pin a workspace in the connector URL

For OAuth connections — Claude.ai and Claude Desktop custom connectors especially — the URL pin is the reliable way to bind a connector to one workspace:

https://api.meldoc.io/mcp?workspace=your-workspace

Without a pin, an account that belongs to several workspaces gets a WORKSPACE_REQUIRED error on tool calls until one is chosen. The Getting Started with MCP builds pinned URLs for you.

Automatic caching

When you use a workspace explicitly — through a tool parameter or natural language — the server caches it as your default for future requests. Switch workspaces and the new choice becomes the default.

If meldoc.config.yml exists in your project, the project binding takes priority. You can still override per-request, but the override won’t be cached.

Set a project-specific workspace

Create meldoc.config.yml in your project root:

workspaceAlias: your-workspace-name

The MCP server uses this workspace automatically when working from that directory.

List and switch workspaces

Ask your AI assistant in natural language:

“List my workspaces” “Switch to the company-docs workspace” “Use personal-workspace for this task”

Your assistant calls list_workspaces and get_workspace behind the scenes. Nothing sets the active workspace: when a token reaches more than one, the choice travels on each call as workspaceAlias, or is pinned once in the connector configuration.

What’s next?

Advanced Usage — Configuration files and environment variables.

Troubleshooting — Fix workspace selection issues.