# Add the freispace MCP server to your LLM

This guide shows you how to connect the freispace MCP server to the most common AI assistants, so you can ask your LLM questions about your freispace data.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before you start, make sure you have:

1. **Node.js** installed (version 18 or later). The MCP server is started via `npx`, which ships with Node.js.

2. Your personal **freispace MCP secret**. Every team member has their own secret, which a team admin can provide from the team settings ([Managing MCP Server Access](https://docs.freispace.com/docs/mcp-server/managing-access.md)). Your secret will look similar to `ai-xxxx`.

caution

Treat your secret like a password. Anyone with it can query freispace data on your behalf.

## Configuration snippet[​](#configuration-snippet "Direct link to Configuration snippet")

Most MCP-capable clients use the same JSON structure to register a server. This is the entry for freispace:

```
"freispace-analytics": {

  "command": "npx",

  "args": ["-y", "@freispace/mcp-server-analytics"],

  "env": {

    "API_KEY": "ai-xxxx"

  }

}
```

Replace `ai-xxxx` with your own API key. The sections below show where this snippet goes for each client.

## Client setup[​](#client-setup "Direct link to Client setup")

* Claude Desktop
* Claude Code
* Google Gemini (CLI)
* Microsoft / GitHub Copilot
* ChatGPT
* Other LLMs

1. Open Claude Desktop and go to **Settings → Developer**.

2. Click **Edit Config**. This opens the `claude_desktop_config.json` file:

   * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

3. Add the freispace server under `mcpServers`:

   ```
   {

     "mcpServers": {

       "freispace-analytics": {

         "command": "npx",

         "args": ["-y", "@freispace/mcp-server-analytics"],

         "env": {

           "API_KEY": "ai-xxxx"

         }

       }

     }

   }
   ```

4. Restart Claude Desktop.

You should now see *freispace-analytics* listed under the tools icon in the chat input. Try asking Claude a question about your freispace data.

Run the following command in your terminal:

```
claude mcp add freispace-analytics --env API_KEY=ai-xxxx -- npx -y @freispace/mcp-server-analytics
```

Alternatively, add the server to a `.mcp.json` file in your project root to share it with your team:

```
{

  "mcpServers": {

    "freispace-analytics": {

      "command": "npx",

      "args": ["-y", "@freispace/mcp-server-analytics"],

      "env": {

        "API_KEY": "ai-xxxx"

      }

    }

  }

}
```

Verify the connection with `claude mcp list`.

The Gemini CLI reads MCP servers from its settings file:

* **Per user:** `~/.gemini/settings.json`
* **Per project:** `.gemini/settings.json` in your project root

Add the freispace server under `mcpServers`:

```
{

  "mcpServers": {

    "freispace-analytics": {

      "command": "npx",

      "args": ["-y", "@freispace/mcp-server-analytics"],

      "env": {

        "API_KEY": "ai-xxxx"

      }

    }

  }

}
```

Restart the Gemini CLI and run `/mcp` to confirm that *freispace-analytics* is connected and its tools are available.

GitHub Copilot in **VS Code** supports MCP servers in agent mode.

1. Create a file named `.vscode/mcp.json` in your workspace (or run the **MCP: Add Server** command from the Command Palette).

2. Add the freispace server. Note that VS Code uses a `servers` key instead of `mcpServers`:

   ```
   {

     "servers": {

       "freispace-analytics": {

         "type": "stdio",

         "command": "npx",

         "args": ["-y", "@freispace/mcp-server-analytics"],

         "env": {

           "API_KEY": "ai-xxxx"

         }

       }

     }

   }
   ```

3. Open the Copilot Chat view, switch to **Agent** mode, and click the tools icon to confirm the freispace tools are listed.

The same configuration also works for Copilot in other JetBrains and Visual Studio setups that support MCP — check your IDE's Copilot settings for where the MCP configuration file lives.

ChatGPT connects to MCP servers through **connectors**, which require a *remotely hosted* MCP server — it cannot launch a local `npx` process like the other clients.

To use freispace with ChatGPT:

1. Expose the freispace MCP server over HTTP using an MCP gateway (for example [supergateway](https://www.npmjs.com/package/supergateway) or a similar stdio-to-HTTP proxy) hosted on infrastructure your company controls:

   ```
   npx -y supergateway --stdio "npx -y @freispace/mcp-server-analytics" --port 8000
   ```

   Make sure the `API_KEY` environment variable is set in the environment where the gateway runs, and that the endpoint is only reachable by authorized users.

2. In ChatGPT, go to **Settings → Connectors**, enable **Developer mode** (requires an eligible plan), and add a new connector pointing to your gateway's URL.

3. Enable the connector in a chat to let ChatGPT query your freispace data.

Any self-hosted LLM stack that supports the [Model Context Protocol](https://modelcontextprotocol.io) and tool calling can use the freispace MCP server. In most clients you register it with the standard configuration:

```
{

  "mcpServers": {

    "freispace-analytics": {

      "command": "npx",

      "args": ["-y", "@freispace/mcp-server-analytics"],

      "env": {

        "API_KEY": "ai-xxxx"

      }

    }

  }

}
```

Consult your client's documentation for the exact location of its MCP configuration file.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

* **Server does not start:** Check that Node.js 18+ is installed and `npx` is available on your `PATH`. Some desktop clients do not inherit your shell's `PATH` — using the absolute path to `npx` can help.

* **Authentication errors:** Verify that the `API_KEY` value matches your current secret. If an admin has regenerated your secret or disabled your access, the old value will stop working — see [Managing MCP Server Access](https://docs.freispace.com/docs/mcp-server/managing-access.md).

* **Tools do not appear:** Most clients only load MCP servers on startup. Fully restart the application after editing the configuration.