Token clients

Setup for apps that connect with a personal API token. Create the token first: see Connect with an API token for permissions, lifetimes and keeping it safe.

In every example below, replace YOUR_API_TOKEN with your token and connect whichever servers you need: https://app.franchisesee.com/mcp/reporting (read-only reporting) and https://app.franchisesee.com/mcp/admin (managing locations and users, HQ only).

GitHub Copilot#

Copilot connects to FranchiseSEE directly over HTTP, with no bridge to install. This works in VS Code, Visual Studio, JetBrains IDEs, Xcode, the Copilot CLI and the Copilot coding agent.

On Copilot Business or Enterprise, your organization's Copilot administrator must first turn on the MCP servers in Copilot policy. If FranchiseSEE doesn't appear, that policy is the most likely reason.

VS Code (Copilot agent mode)#

Add the servers to .vscode/mcp.json in your workspace, or to your user MCP configuration. The inputs entry makes VS Code ask for your token once and store it securely, so the token never appears in the file:

{
  "servers": {
    "franchisesee-reporting": {
      "type": "http",
      "url": "https://app.franchisesee.com/mcp/reporting",
      "headers": {
        "Authorization": "Bearer ${input:franchisesee-token}"
      }
    },
    "franchisesee-admin": {
      "type": "http",
      "url": "https://app.franchisesee.com/mcp/admin",
      "headers": {
        "Authorization": "Bearer ${input:franchisesee-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "franchisesee-token",
      "type": "promptString",
      "description": "FranchiseSEE API token",
      "password": true
    }
  ]
}

Start the servers from the MCP view, and the FranchiseSEE tools appear in Copilot's agent mode. The reporting server's guided prompts appear as slash commands, such as /mcp.franchisesee-reporting.analyze-performance.

Visual Studio, JetBrains IDEs, Xcode and the Copilot CLI take the same entries (type: "http", the URL and the Authorization header) in their own MCP configuration files.

Copilot coding agent (github.com)#

A repository administrator adds the server under the repository's Settings, in Code, planning, and automation, then Copilot, then MCP servers:

{
  "mcpServers": {
    "franchisesee-reporting": {
      "type": "http",
      "url": "https://app.franchisesee.com/mcp/reporting",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_FRANCHISESEE_TOKEN"
      },
      "tools": ["*"]
    }
  }
}

Store the token as an environment secret named COPILOT_MCP_FRANCHISESEE_TOKEN in the repository's copilot environment. Secrets that start with COPILOT_MCP_ reach only MCP servers. The tools list is required: ["*"] allows every tool, or list tool names to allow fewer.

• Use a read-only token, and only the reporting server. Anyone who can assign work to the coding agent acts with that token. Don't give the coding agent the admin server.
• Firewall. The coding agent runs behind an outbound firewall. If it can't connect, add app.franchisesee.com to the agent's allowlist in the repository's Copilot settings.

The coding agent uses tools only; the guided prompts aren't available there.

Claude Code with a token#

Sign-in is simpler for the reporting server (see Developer tools). For the admin server, pass the token as a header:

claude mcp add --transport http franchisesee-admin https://app.franchisesee.com/mcp/admin \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Claude Desktop with mcp-remote#

Claude Desktop connects by signing in (see Claude). To use a token instead, for example to reach the admin server, bridge the server with mcp-remote. This needs Node.js; npx downloads the bridge on first use.

Edit Claude Desktop's configuration file:

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

{
  "mcpServers": {
    "franchisesee-admin": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.franchisesee.com/mcp/admin",
        "--header",
        "Authorization: Bearer YOUR_API_TOKEN"
      ],
      "env": {
        "PATH": "PASTE_YOUR_FULL_PATH_HERE"
      }
    }
  }
}

Setting env.PATH#

This is the step that trips people up. Claude Desktop doesn't start from your terminal, so it doesn't inherit your shell's PATH. The bridge needs PATH to find two things, and both must be there:

1. npx and node: the folder Node.js was installed into.
2. System tools: sh on macOS and Linux, the system folders on Windows. npx runs them, and without them the server disconnects at once. On macOS and Linux the error is npm error spawn sh ENOENT. A PATH holding only the Node folder is the usual cause.

The simplest value that has both is your terminal's own PATH. Leave command as plain "npx"; Claude Desktop finds it through the PATH you give it.

macOS and Linux. Run this in Terminal, copy the whole line it prints, and paste it as the env.PATH value:

echo "$(dirname "$(command -v npx)"):$PATH"

The value is a list separated by colons. Folders with spaces in them, such as Application Support, need no quoting.

Windows. Run this in Command Prompt (cmd.exe), not PowerShell, and paste the result:

echo %PATH%

The value is a list separated by semicolons. In the JSON file, backslashes must be doubled (C:\\Program Files\\nodejs); if Claude Desktop reports a JSON error, that's the likely cause.

Save the file and restart Claude Desktop. FranchiseSEE appears among its connected servers.

Other MCP clients#

Any client that supports the Streamable HTTP transport can connect directly by sending the token with each request:

POST https://app.franchisesee.com/mcp/reporting
Authorization: Bearer YOUR_API_TOKEN

Something wrong?#

See Troubleshooting: API tokens.