Integrating with the Magic Suite MCP Server

This page covers connecting an AI client to the Magic Suite MCP Server. There is a section below for each of the common clients; if yours is not listed, the generic settings at the end are all you need.

1. Choose your endpoint

For production Magic Suite, the MCP endpoint is:

https://mcp.magicsuite.net/

Every other environment follows the same pattern as its API: wherever you would use api.<environment>.magicsuite.net, the MCP endpoint is mcp.<environment>.magicsuite.net.

Use the endpoint matching the environment your API Token belongs to - a token issued on one environment will not authenticate against another.

The MCP Server was introduced in Magic Suite 4.5, so an environment only has an endpoint once it is running 4.5 or later.

2. Create an API Token

In Magic Suite, go to Admin > API Tokens and create a token. You will need two values:

the token name;
the token key, which is shown only once - copy it before leaving the page.

The token inherits the rights of the user who owns it, so use a user whose access matches what you want the assistant to be able to do. If you only need the assistant to answer questions, use a user without write access.

3. The header

The server speaks MCP over Streamable HTTP. Every client below is doing the same thing: pointing at the endpoint and sending one HTTP header.

Authorization: Bearer {apiTokenName}:{apiTokenKey}

The form the Magic Suite REST API itself accepts also works, so an existing header can be pasted unchanged:

Authorization: Bearer v2 token:{apiTokenName}/{apiTokenKey}

Throughout the examples below, replace my-token:my-key with your own token name and key.

Anthropic Claude

Claude Code

One command:

claude mcp add --transport http magicsuite https://mcp.magicsuite.net/ \
  --header "Authorization: Bearer my-token:my-key"

Add --scope project to share the server with a repository (it is written to .mcp.json - do not commit a real key), or --scope user to make it available in every project on your machine. Check it with claude mcp list.

Claude Desktop and claude.ai

Go to Settings > Connectors > Add custom connector, enter the endpoint URL, and add the Authorization header under Request headers. Claude stores the value securely and sends it on every request.

Two caveats: request-header authentication is a beta feature and may not be enabled on your account yet, and Claude accepts only a fixed set of standard header names (authorization is one of them). If the Request headers section is not available to you, use Claude Code instead, or bridge through mcp-remote in the desktop configuration file:

{
  "mcpServers": {
    "magicsuite": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.magicsuite.net/",
        "--header", "Authorization: Bearer my-token:my-key"
      ]
    }
  }
}

GitHub Copilot (VS Code)

Create .vscode/mcp.json in your workspace. Using an input rather than a literal keeps the key out of the file - VS Code prompts once and then stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "magicsuite-token",
      "description": "Magic Suite API token (name:key)",
      "password": true
    }
  ],
  "servers": {
    "magicsuite": {
      "type": "http",
      "url": "https://mcp.magicsuite.net/",
      "headers": {
        "Authorization": "Bearer ${input:magicsuite-token}"
      }
    }
  }
}

Open the Chat view in Agent mode and the tools appear under the tools picker. For a server you want in every workspace, run MCP: Open User Configuration from the Command Palette and add the same servers entry there instead.

OpenAI Codex

Codex reads ~/.codex/config.toml (or .codex/config.toml in a trusted project). A remote server needs a url; the credential comes either from an environment variable via bearer_token_env_var, or from a literal header.

Preferred - keep the key in an environment variable:

[mcp_servers.magicsuite]
url = "https://mcp.magicsuite.net/"
bearer_token_env_var = "MAGICSUITE_MCP_TOKEN"

Set MAGICSUITE_MCP_TOKEN to my-token:my-key - Codex sends it as Authorization: Bearer <value>.

Alternatively, as a literal header:

[mcp_servers.magicsuite]
url = "https://mcp.magicsuite.net/"
http_headers = { "Authorization" = "Bearer my-token:my-key" }

Add enabled = false to turn a server off without deleting its configuration.

Cursor

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json to make it available everywhere. Cursor supports ${env:...} interpolation, so the key need not be in the file:

{
  "mcpServers": {
    "magicsuite": {
      "url": "https://mcp.magicsuite.net/",
      "headers": {
        "Authorization": "Bearer ${env:MAGICSUITE_MCP_TOKEN}"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (on Windows, %USERPROFILE%\.codeium\windsurf\mcp_config.json). Note that Windsurf uses serverUrl rather than url:

{
  "mcpServers": {
    "magicsuite": {
      "serverUrl": "https://mcp.magicsuite.net/",
      "headers": {
        "Authorization": "Bearer ${env:MAGICSUITE_MCP_TOKEN}"
      }
    }
  }
}

Gemini CLI

Add the server to ~/.gemini/settings.json. Gemini CLI uses httpUrl for Streamable HTTP servers:

{
  "mcpServers": {
    "magicsuite": {
      "httpUrl": "https://mcp.magicsuite.net/",
      "headers": {
        "Authorization": "Bearer my-token:my-key"
      }
    }
  }
}

Any other MCP client

There is nothing Magic Suite-specific about the connection. Give the client:

Transport: Streamable HTTP (not stdio, and not the deprecated HTTP+SSE transport).
URL: the endpoint for your environment, from the table at the top of this page.
Header: Authorization: Bearer {apiTokenName}:{apiTokenKey}.

If a client only supports stdio servers, bridge to it with mcp-remote, as shown in the Claude Desktop section above.

4. Check the connection

Ask your assistant to run the health_check tool. It reports whether the Magic Suite API is reachable, and which user and tenant your token authenticates as - a quick way to confirm you connected with the token you meant to use.

To test without an assistant, use the MCP Inspector:

npx -y @modelcontextprotocol/inspector --cli https://mcp.magicsuite.net/ \
  --transport http --header "Authorization: Bearer my-token:my-key" \
  --method tools/list

Troubleshooting

Symptom	Cause
`401 Unauthorized` immediately on connect	The `Authorization` header is missing or not in one of the two forms above. Check for a missing colon between the token name and key, and check the client is actually sending the header - some clients silently drop headers they do not recognise.
Connects, but every tool call fails with 401	The header parsed, but Magic Suite rejected the token. It may have been regenerated or deleted, or you may be pointing at an endpoint for a different environment than the one the token belongs to.
A tool call fails with 403	The token is valid but its owner lacks rights for that operation. Grant the user the access, or use a token from a user who already has it.
The assistant cannot find an entity	Ask it to run `odata_entity_sets` to list the exact names available.
A query fails asking for an order	Paging needs one: supply `orderby` whenever you use `top` or `skip`.
The client cannot connect at all	Confirm the client supports Streamable HTTP. Clients written against the older HTTP+SSE transport cannot connect; bridge them with `mcp-remote`.
The hostname does not resolve	That environment is not yet running Magic Suite 4.5, or has not had its MCP endpoint provisioned. Check the environment's version first.

Keeping the key safe

An API Token key is a credential equivalent to the owner's password. Do not commit it to a repository. Prefer your client's secret-input or environment-variable mechanism over a literal in a configuration file, and regenerate the token in Admin > API Tokens if it is ever exposed.

Integrating with the Magic Suite MCP Server