Connect Claude Code, Cursor, Windsurf, and VS Code to Norbelys over MCP

Five clients, one server, two ways in. This is the setup guide with no detours — if you already know why you’d want an agent driving Norbelys, that post is here; this one is just the steps.

Every client below points at the same endpoint:

https://mcp.norbelys.com/mcp

And every client authenticates one of two ways: an organization-scoped API key (ak_…, works everywhere, best for headless/CI use) or OAuth 2.1 (only for clients with a real sign-in flow — you pick your workspace during consent, no key to paste or leak).

All five clients end up talking to the same 83-tool catalog once connected — this guide is only about getting each one to that point without guessing at a config format.

Get a key first

Claude Code

The fastest path — one command, no config file to hand-edit.

Terminal

$ claude mcp add norbelys --transport http https://mcp.norbelys.com/mcp \$ --header "Authorization: Bearer ak_<org-scoped-api-key>"MCP server "norbelys" added

That registers the server for Claude Code’s current scope — by default, scoped to the project you ran it from. If you want the connection available everywhere instead, add --scope user to the same command; if you’re setting this up for a team, --scope project writes it into a checked-in .mcp.json instead of your personal config, so everyone who clones the repo gets the same server without re-running the command. Verify it landed before doing anything else:

Terminal

$ claude mcp listnorbelys http https://mcp.norbelys.com/mcp ✓ connected

Then, inside a Claude Code session, ask it to call organization_find. If it comes back with your workspace name, the credential and the transport are both good.

Claude Desktop / custom connectors

Claude’s connector UI skips the key entirely and runs a real sign-in.

Cursor

Cursor reads MCP servers from a JSON config file, either per-project (.cursor/mcp.json) or global (~/.cursor/mcp.json).

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "norbelys": {
      "url": "https://mcp.norbelys.com/mcp",
      "headers": { "Authorization": "Bearer ak_<org-scoped-api-key>" }
    }
  }
}

Save the file, then reload Cursor’s MCP servers from its settings panel (or restart the app). Cursor lists connected servers with their tool counts — you’re looking for norbelys with roughly 80 tools attached.

Windsurf

Windsurf’s format is the same shape as Cursor’s, in its own config file: ~/.codeium/windsurf/mcp_config.json on macOS/Linux, or %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows.

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "norbelys": {
      "serverUrl": "https://mcp.norbelys.com/mcp",
      "headers": { "Authorization": "Bearer ak_<org-scoped-api-key>" }
    }
  }
}

If the file doesn’t exist yet, Windsurf’s Cascade panel has a “Configure MCP servers” entry that creates it for you — open that, then paste the same block in via its raw-config editor. Restart Windsurf after saving.

Windsurf also supports ${env:VAR_NAME} interpolation inside this file, so "Authorization": "Bearer ${env:NORBELYS_API_KEY}" reads the key from your shell environment instead of storing it in the config — worth using if this file ever ends up anywhere shared.

GitHub Copilot and other MCP-aware editors

Any client that speaks Streamable HTTP with a bearer header follows the same three facts, even if it isn’t listed above by name: the URL is https://mcp.norbelys.com/mcp, the header is Authorization: Bearer ak_… (or whatever the client’s OAuth flow produces), and there’s no third field to configure. If a client’s docs ask for a “transport type,” it’s HTTP, not SSE or stdio — the Norbelys server doesn’t run a local process for anything.

VS Code

VS Code’s built-in MCP support reads a servers map, either workspace-scoped (.vscode/mcp.json, good for a team default) or in your user profile.

// .vscode/mcp.json
{
  "servers": {
    "norbelys": {
      "type": "http",
      "url": "https://mcp.norbelys.com/mcp",
      "headers": { "Authorization": "Bearer ak_<org-scoped-api-key>" }
    }
  }
}

Open the Command Palette and run MCP: List Servers to confirm norbelys shows as running, or start it directly from there if it doesn’t connect automatically.

The type: "http" field matters — VS Code also supports local stdio servers, and a config missing that field or pointed at the wrong transport type is the most common reason a remote server silently fails to start.

If a client won’t connect

A handful of things account for nearly every failed first connection, regardless of client:

• A default User-Agent gets blocked. Some minimal HTTP clients (bare Python scripts are the common case) send a User-Agent the edge rejects. Every mainstream MCP client sets its own, so this mostly bites custom integrations — the tool catalog post and the full developer portal both link through to the public docs if you’re debugging one.
• A stale or revoked key. If the key worked yesterday and doesn’t today, check whether it was rotated or revoked — key hygiene covers why that happens on purpose, not just by accident.
• A key with no organization attached. Every credential must resolve to exactly one workspace. If organization_find comes back with a no_active_organization error instead of your org, the key itself is the problem, not the client config — mint a new one from a workspace you’re actually a member of.

The same first call, everywhere

Once any client shows the server connected, run the same check regardless of which one you used: ask it to call organization_find, then organization_pulse. The first confirms which workspace the credential resolves to; the second is a one-call briefing — every campaign, the mailbox fleet, your deliverability headline. If both come back clean, the setup is done and every other tool in the catalog is reachable the same way.

From here, the two things worth doing next are scoping the key you just pasted down to what the agent actually needs — least-privilege key hygiene — and, if you’re handing this to an agent that runs on its own, deciding up front what it’s allowed to do unattended versus what needs a human gate before anything reaches a real inbox.