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

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). 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

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

Claude Desktop

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.

Claude Code

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.

Google Gemini (CLI)

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.

Microsoft / GitHub Copilot

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

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 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.

Other LLMs

Any self-hosted LLM stack that supports the Model Context Protocol 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

• 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.

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