00

Before you start

1. Add at least one skill to your Loadout.
2. Create a personal token on Connect. It's shown once — copy it then. It starts with ph_live_.
3. Your endpoint is https://perkhubs.space/mcp

Keep the token out of config files

Most clients can read the token from an environment variable, so the config files you commit or share never contain it. The guides below use PERKHUBS_TOKEN.

export PERKHUBS_TOKEN="ph_live_your_token"

setx PERKHUBS_TOKEN "ph_live_your_token"

Open a new terminal (and restart the editor) afterwards so the app sees the variable. Commands below use bash syntax; in PowerShell write $env:PERKHUBS_TOKEN instead of $PERKHUBS_TOKEN, and curl.exe instead of curl.

01

claude.ai & Claude Desktop

1. On Connect, choose claude.ai / Claude Desktop and copy the connector URL. It already contains your token.
2. In Claude, open Settings → Connectors → Add custom connector.
3. Paste the URL, name it PerkHubs, and add it. No sign-in is needed.
4. In a chat, open the tools menu and make sure PerkHubs is on.

https://perkhubs.space/mcp?token=ph_live_your_token

This URL contains your token. Don't paste it into chats, screenshots or shared docs. If it leaks, regenerate the token on Connect.

Connector settings live in Settings → Connectors; the menu name can vary between versions.

02

Claude Code

Run once in a terminal. --scope user makes it available in every project.

claude mcp add --transport http --scope user perkhubs https://perkhubs.space/mcp --header "Authorization: Bearer $PERKHUBS_TOKEN"

Or share it with a project through .mcp.json at the repo root — the token stays in each person's environment:

{
  "mcpServers": {
    "perkhubs": {
      "type": "http",
      "url": "https://perkhubs.space/mcp",
      "headers": {
        "Authorization": "Bearer ${PERKHUBS_TOKEN}"
      }
    }
  }
}

Check with /mcp inside Claude Code. Project servers ask for your approval the first time.

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

03

Cursor

Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one. Merge the perkhubs entry if the file already exists.

{
  "mcpServers": {
    "perkhubs": {
      "url": "https://perkhubs.space/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PERKHUBS_TOKEN}"
      }
    }
  }
}

Then open Cursor Settings → MCP and check that PerkHubs shows its tools.

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

04

VS Code (GitHub Copilot agent mode)

Create .vscode/mcp.json. VS Code asks for the token the first time and stores it securely.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perkhubs-token",
      "description": "PerkHubs personal token",
      "password": true
    }
  ],
  "servers": {
    "perkhubs": {
      "type": "http",
      "url": "https://perkhubs.space/mcp",
      "headers": {
        "Authorization": "Bearer ${input:perkhubs-token}"
      }
    }
  }
}

Start the server from the file's CodeLens or the MCP view, then use Copilot Chat in Agent mode.

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

05

Codex CLI

Add to ~/.codex/config.toml. Codex reads the token from the variable you name; it never goes in the file.

[mcp_servers.perkhubs]
url = "https://perkhubs.space/mcp"
bearer_token_env_var = "PERKHUBS_TOKEN"

Restart Codex from a shell where PERKHUBS_TOKEN is set.

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

06

Gemini CLI

gemini mcp add --scope user --transport http --header "Authorization: Bearer $PERKHUBS_TOKEN" perkhubs https://perkhubs.space/mcp

Or edit ~/.gemini/settings.json directly — note the key is httpUrl for this kind of server:

{
  "mcpServers": {
    "perkhubs": {
      "httpUrl": "https://perkhubs.space/mcp",
      "headers": {
        "Authorization": "Bearer ${PERKHUBS_TOKEN}"
      }
    }
  }
}

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

07

Windsurf / Devin Desktop

Windsurf's Cascade now ships as Devin Desktop. Its MCP file is ~/.config/devin/mcp_config.json on macOS/Linux and %APPDATA%\devin\mcp_config.json on Windows; older Windsurf builds use ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "perkhubs": {
      "serverUrl": "https://perkhubs.space/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PERKHUBS_TOKEN}"
      }
    }
  }
}

Syntax checked against the client's official docs on 8 Oct 2026. Clients change; if a step differs, follow their docs.

08

Any other client

If a client supports remote MCP servers, give it the endpoint and an Authorization: Bearer header. If it only runs local (stdio) servers, bridge with mcp-remote:

{
  "mcpServers": {
    "perkhubs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://perkhubs.space/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ph_live_your_token"
      }
    }
  }
}

Writing Authorization:${AUTH_HEADER} without a space avoids a Windows bug where spaces inside args break the command.

mcp-remote is an open-source bridge (github.com/geelen/mcp-remote); it needs Node.js.

09

Test the connection

1. Check the token from a terminal. A working token answers with "status":"ok":

   curl -H "Authorization: Bearer $PERKHUBS_TOKEN" https://perkhubs.space/mcp

2. Start a new chat and ask: “Which PerkHubs skills do you have?” The agent already knows your active skills from the moment it connects.
3. On Connect, press Check connection activity to see which agent reached PerkHubs and when.

Optional: nudge the agent

If an agent doesn't reach for skills on its own, add this line to your project's AGENTS.md or CLAUDE.md:

Before a task, check the PerkHubs skills listed in your MCP server instructions and use get_skill when one fits.

10

Troubleshooting

401 Invalid token

The token was regenerated or revoked, or the variable is empty in the app's environment. Create a new token on Connect, update the variable, and restart the app.

No PerkHubs tools appear

Restart or reload the client after editing its config, and check the file location for your client above. Some clients only list servers that connected without errors.

The agent sees old skills

The list is sent when the agent connects. Start a new session, or ask it to call list_active_skills.

A skill is missing

It must be switched on in your Loadout and within your plan's active-skill limit. Private skills reach only their owner.

429 Too many requests

The limit is 120 requests per minute per token. Wait a minute; if an agent loops, stop it and start a new session.

Windows: the server won't start

Use the Authorization:${AUTH_HEADER} form from “Any other client”, and open a new window after setx.

Still stuck? Use the contact on the Privacy page. What PerkHubs records about each call is listed there too.