Claude Desktop

Claude Desktop has two ways to talk to vTilt:

1. OAuth Connector (recommended) — Recent builds of Claude Desktop ship a built-in remote MCP connector that handles OAuth 2.1 + PKCE automatically. You point Claude at the MCP URL, sign in to vTilt in your browser, and approve the consent screen. No vtu_ key, no npx.
2. mcp-remote bridge — A small npm package that runs a stdio MCP server locally and forwards JSON-RPC frames to vTilt's HTTPS endpoint over a vtu_ Bearer token. Use this if your Claude Desktop build doesn't expose OAuth connectors yet.

#Connect via OAuth (recommended)

1. Open Claude Desktop → Settings → Connectors.
2. Click Add custom connector.
3. Set:
   • Name: vTilt
   • URL: https://www.vtilt.com/api/mcp
4. Click Connect. Claude opens your browser at vTilt's sign-in page.
5. Sign in (or use an existing dashboard session). vTilt shows a consent screen listing the scopes Claude is requesting (mcp:read, offline_access, openid, email). Click Allow.
6. Back in Claude Desktop, the connector appears in the 🔌 menu with all MCP tools available.

Claude refreshes its OAuth tokens in the background — you won't see the consent screen again until you remove the connector. See the OAuth guide for the full flow, scopes, and error reference.

#Pin a project (multi-project users)

The OAuth Connector also accepts custom headers. Add x-vtilt-project-id with your project id, or call the switch-project tool mid-conversation. Single-project accounts don't need to pin.

#Connect via mcp-remote bridge

If your Claude Desktop build doesn't expose OAuth connectors yet, use the official mcp-remote bridge. This is the pattern most remote MCP servers (PostHog, Neon, Linear, …) recommended before OAuth landed.

#1. Locate the Claude Desktop config file

Open the file in your editor — create it if it doesn't exist.

#2. Add the vTilt server

{
  "mcpServers": {
    "vtilt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.vtilt.com/api/mcp",
        "--header",
        "Authorization: Bearer vtu_YOUR_SECRET"
      ]
    }
  }
}

Save the file and fully quit and relaunch Claude Desktop (Claude reads MCP config only at startup).

#3. Pin a project (multi-project users only)

Pass an extra --header for the project pin:

{
  "mcpServers": {
    "vtilt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.vtilt.com/api/mcp",
        "--header",
        "Authorization: Bearer vtu_YOUR_SECRET",
        "--header",
        "x-vtilt-project-id: YOUR_PROJECT_ID"
      ]
    }
  }
}

Single-project accounts don't need this — the server auto-pins.

#4. Verify the connection

In a new Claude conversation, look for the 🔌 icon in the bottom-left of the input box — it lists every connected MCP server. vtilt should appear; click it to see the seven tools.

Then ask:

What MCP tools do you have available from vtilt?
List them by name with a one-line description each.

Claude will call tools/list and read the descriptions back.

#5. Try a real prompt

Use the vtilt tools to summarise the last 50 events in my
project. Group by event name and show counts.

Claude calls events-recent, parses the JSON, and writes a markdown summary. The same shape works for any of the seven tools — Claude figures out which to use from your prompt.

#6. Authorisation flow (advanced)

mcp-remote also supports OAuth — if your Claude Desktop build supports the built-in OAuth Connector you can skip the bridge entirely. Otherwise keep --header Authorization: Bearer vtu_…. See the OAuth guide for the full flow.

#Troubleshooting

• vtilt doesn't appear in the 🔌 menu — Claude couldn't start the bridge. Check ~/Library/Logs/Claude/mcp.log (macOS) or %APPDATA%\Claude\logs\mcp.log (Windows) — usually the issue is npx not being on PATH inside Claude's launch env. Fix: install Node.js system-wide, or replace "command": "npx" with the absolute path (/usr/local/bin/npx, C:\\Program Files\\nodejs\\npx.cmd).
• "Unauthorized" — bearer header is missing, malformed, revoked, or expired. See error table.
• "Forbidden — project_not_accessible" — x-vtilt-project-id points at a project you don't have access to. Remove the header or pick a project from your dashboard.
• First request is slow — npx -y mcp-remote downloads the package on first launch (~5–10s on a slow link). Subsequent launches reuse the cached install.

#Next steps

• OAuth — full OAuth 2.1 + PKCE flow, scopes, and consent UX.
• Authentication — both auth paths plus the vtu_ key lifecycle and error reference.
• MCP server overview — the seven phase-1 tools and example prompts.
• Cursor — same vTilt account, different client.