VS Code

Visual Studio Code runs MCP servers in GitHub Copilot’s agent mode. Servers are defined in an mcp.json file. Use the hosted server with a header token, or the local stdio server for full read/write.

Tested versions

The Chat view lets you pick which agent runs a chat session — for example Local or Copilot CLI. This is a VS Code chat setting and is separate from the choice between the hosted and local MCP servers below.

This page was last checked on 15 October 2026 with VS Code 1.141.1, using the Local agent: both the hosted and local servers below worked there. The same setup also worked with VS Code 1.138.0 on 7 October 2026.

Use the Local agent. Observed with VS Code 1.141.1 and the Copilot CLI agent (Copilot CLI 1.0.92-4), October 2026: VS Code shows the token prompt from the inputs block but doesn’t substitute the value you enter, so the server receives the literal text ${input:datamesh-token} instead of your token. The local server then reports Invalid token, and the hosted server rejects the request (HTTP 401), after which VS Code opens a sign-in dialog that fails. Select the Local agent in the Chat view when you use the Datamesh tools.

Also observed with VS Code 1.141.1: MCP servers only start after you send the first chat message, so the token prompt appears then rather than when you open the workspace.

Hosted server (http)

Create .vscode/mcp.json in your workspace (or run MCP: Open User Configuration from the Command Palette for a global config), and add an HTTP server:

{
  "servers": {
    "oceanum-datamesh-hosted": {
      "type": "http",
      "url": "https://mcp.oceanum.io/datamesh",
      "headers": {
        "X-DATAMESH-TOKEN": "${input:datamesh-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "datamesh-token",
      "description": "Datamesh token",
      "password": true
    }
  ]
}

The inputs block prompts you for your Datamesh token the first time the server starts and keeps it out of the file — use it by default. The server doesn’t start until it’s first needed: observed with VS Code 1.141.1, that is after you send your first chat message, so expect the prompt then.

Hosted sign-in (the “sign in with Oceanum.io” OAuth flow) currently doesn’t work for VS Code, so authenticate with the token header as shown. If VS Code opens a sign-in dialog for this server, the token didn’t reach the server — see Troubleshooting.

Token in the file

The inputs prompt above is the recommended setup. If you can’t use it, you can put the token itself in headers and drop the inputs block:

{
  "servers": {
    "oceanum-datamesh-hosted": {
      "type": "http",
      "url": "https://mcp.oceanum.io/datamesh",
      "headers": {
        "X-DATAMESH-TOKEN": "your-datamesh-token"
      }
    }
  }
}

The file then holds your credential in plain text. The token grants your account’s full Datamesh access — read, modify and delete — through the Datamesh APIs and the local server, regardless of which MCP server you configure it for; the hosted server being read-only doesn’t make a leaked token low-risk. Anyone who can read the file can use it. Keeping it in your user configuration rather than a workspace .vscode/mcp.json avoids committing it with a project, but the user configuration is still a plain-text file that may be synced or backed up. Never commit or share a file that contains the token.

Large data

The hosted server is read-only and returns query_data results inline (up to ~50 MB), so large results can’t come back in the conversation. To get large data, call export_query: on the hosted server it returns a time-limited download link to the full result, which you fetch out-of-band (e.g. with curl) — the link needs no token, so treat it like a password. The local server below instead writes export_query output to a file on your machine.

Local server (stdio)

For full read/write, and to have export_query write results straight to a file on your machine (NetCDF, Parquet or CSV) rather than return a download link, run the server locally:

{
  "servers": {
    "oceanum-datamesh-local": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--python", "3.13", "oceanum-mcp", "datamesh"],
      "env": { "DATAMESH_TOKEN": "${input:datamesh-token}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "datamesh-token",
      "description": "Datamesh token",
      "password": true
    }
  ]
}

This requires uv on your PATH. The --python 3.13 argument has uv run the server on Python 3.13 (downloading it if needed), as some of the server’s dependencies don’t yet install on Python 3.14. Open the Chat view, choose the Local agent, switch to Agent mode and select Tools to confirm the Datamesh tools are available. If they aren’t listed yet, send a chat message first so that VS Code starts the server.

Use one server at a time

The examples use different names — oceanum-datamesh-hosted and oceanum-datamesh-local — so the entries don’t clash, but have only one of them active at a time. Observed with VS Code 1.141.1: with both configured, VS Code restarted, on its own, a server that had been stopped, and the chat then used it, and nothing in the chat showed which server a tool call went to. You can’t tell whether a result came from the read-only hosted server or the read/write local server.

Stopping a server isn’t enough: per VS Code’s MCP server documentation, a later request can start a stopped server again. To switch between the hosted server (for exploration) and the local server (for exports to files), either edit mcp.json so that it contains only the entry you want, or keep both entries and disable the one you aren’t using — run MCP: List Servers from the Command Palette, select the server and choose a disable action. VS Code documents that a disabled server doesn’t start; switching this way wasn’t part of the October 2026 testing.

Troubleshooting

Symptom	Likely cause	Fix
Local server reports `Invalid token`; or the hosted server returns 401 and VS Code opens a sign-in dialog that fails	The token didn’t reach the server: you’re using the Copilot CLI agent, which didn’t substitute `${input:...}` variables in VS Code 1.141.1; or the `headers`/`env` entry is wrong. Hosted sign-in doesn’t currently work for VS Code, so the dialog can’t succeed	Cancel any sign-in dialog, switch to the Local agent and check the `headers` or `env` entry
As above, while using the Local agent with a correct config	The token is invalid — for example mistyped, expired or revoked	Check the token on your Datamesh token page
No token prompt, or the Datamesh tools aren’t listed	In VS Code 1.141.1, MCP servers only start after the first chat message	Send a chat message
A server you stopped starts again, or results come from the server you didn’t expect	Both the hosted and local servers are configured and enabled	Keep only one entry in `mcp.json`, or disable the other server (see Use one server at a time)

Keep your token safe

Your Datamesh token grants access to all of your organisation’s permissioned datasources — including the ability to modify or delete them. Treat it as a secret, and prefer the hosted read-only server for exploratory use.