Agent Setup

After running waypoint init, your agent needs to know how to connect to your Waypoint server's MCP endpoint. The server URL and API key determine where the agent fetches context from.

Prerequisites

• Waypoint server URL (e.g., https://waypoint.yourcompany.com)
• API key with sessions:read scope (issued by your server admin)
• Server is reachable from your network (cloud, on-prem, or internal)

Claude Code

Claude Code is available across CLI, desktop app, and IDE extensions. All surfaces pick up .mcp.json from the project root — set it once, and it works everywhere.

Configuration

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "waypoint": {
      "type": "http",
      "url": "https://waypoint.yourcompany.com/api/mcp",
      "headers": {
        "Authorization": "Bearer wp_..."
      }
    }
  }
}

Replace:

• https://waypoint.yourcompany.com with your server URL
• wp_... with your API key

Commit .mcp.json to the repository — every developer who clones it gets the connection automatically. The API key should be per-developer; each developer replaces wp_... with their own key, or use an environment variable:

{
  "mcpServers": {
    "waypoint": {
      "type": "http",
      "url": "https://waypoint.yourcompany.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${WAYPOINT_API_KEY}"
      }
    }
  }
}

Verify

Start a session and call:

get_waypoint_context("src/main.ts")

If the tool returns results, you're connected. If you see "Unauthorized" or "Forbidden", double-check the URL and API key.

All surfaces covered

• CLI: claude reads .mcp.json from the current directory
• Desktop app: Reads .mcp.json from the project root
• VS Code extension: Reads .mcp.json from the workspace root
• JetBrains: Reads .mcp.json from the project root

No per-surface configuration needed.

GitHub Copilot (VS Code)

VS Code Copilot supports HTTP-based MCP servers via .vscode/mcp.json or VS Code user settings.

Configuration

Project level (.vscode/mcp.json in your repo — commit this):

{
  "servers": {
    "waypoint": {
      "url": "https://waypoint.yourcompany.com/api/mcp",
      "headers": {
        "Authorization": "Bearer wp_..."
      }
    }
  }
}

User level (~/.config/Code/User/settings.json on Mac/Linux, %APPDATA%\Code\User\settings.json on Windows):

{
  "mcp.servers": {
    "waypoint": {
      "url": "https://waypoint.yourcompany.com/api/mcp",
      "headers": {
        "Authorization": "Bearer wp_..."
      }
    }
  }
}

Verify

In VS Code Copilot chat, ask the agent to call get_waypoint_context("src/main.ts"). If it returns session history, you're connected.

Cursor (IDE)

Cursor reads MCP configuration from ~/.cursor/mcp.json or ~/.config/Cursor/mcp.json (Linux).

Configuration

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "waypoint": {
      "url": "https://waypoint.yourcompany.com/api/mcp",
      "auth": {
        "type": "bearer",
        "token": "wp_..."
      }
    }
  }
}

Replace:

• https://waypoint.yourcompany.com with your server URL
• wp_... with your API key

Verify

Start a Cursor session and call get_waypoint_context in the chat.

Manual hook setup (optional)

If you want Cursor to automatically record sessions like Claude Code, add to $REPO/.cursor/hooks.json:

{
  "stop": [
    {
      "type": "command",
      "command": "waypoint generate"
    }
  ]
}

This runs waypoint generate after each session, assuming the Waypoint CLI is in your PATH.

CLI (Terminal / Headless)

The CLI uses environment variables or the config file at ~/.waypoint/config.json.

Configuration

Option 1: Config file (set once, used by all CLI invocations):

waypoint connect https://waypoint.yourcompany.com

You'll be prompted for your API key. Config is saved to ~/.waypoint/config.json with 0600 permissions.

Option 2: Environment variables (takes precedence over config file):

export WAYPOINT_SERVER_URL=https://waypoint.yourcompany.com
export WAYPOINT_API_KEY=wp_...

Add these to your shell profile (.bashrc, .zshrc, etc.) to persist across terminal sessions.

Verify

waypoint show src/main.ts

If the command returns session history for that file, you're connected.

In scripts

For CI/CD or automated scripts, use environment variables:

#!/bin/bash
export WAYPOINT_SERVER_URL="https://waypoint.yourcompany.com"
export WAYPOINT_API_KEY="$WAYPOINT_API_KEY_SECRET"  # from CI secrets

waypoint show src/main.ts

Troubleshooting

"Unauthorized" or "Forbidden"

• Double-check the API key — copy-paste to avoid typos
• Verify the key has sessions:read scope (ask your admin if unsure)
• Ensure the key hasn't expired or been revoked

"Cannot reach server"

• Verify the server URL is correct (no typos, correct domain/port)
• Check that your network can reach the server (ping, curl, or check firewall rules)
• For on-prem servers: ensure your VPN is connected if required
• For cloud servers: check that your IP isn't blocked by WAF or security groups

"No Waypoint history found"

This is expected for new files. Sessions only accumulate as you work. After a few days on an active project, most files will have meaningful context.

Tool not appearing in agent

• Restart your agent or IDE after updating configuration
• If using Claude Code: verify .claude/settings.json exists in the project root
• If using Copilot: verify VS Code's MCP configuration was reloaded (try restarting VS Code)
• If using Cursor: verify ~/.cursor/mcp.json exists and is valid JSON

"Invalid API key" errors

• API keys begin with wp_ — if yours doesn't, it's malformed
• Verify you copied the entire key without truncation
• Ask your admin to issue a new key if the original is lost

Multi-repo setup

If you work across multiple repositories, configure at three levels:

1. User-level (applies to all repos): Set WAYPOINT_SERVER_URL and WAYPOINT_API_KEY in your shell profile
2. Project-level (overrides user): Each repo has its own .claude/settings.json or .cursor/mcp.json
3. Session-level (highest priority): waypoint connect <url> overwrites user config for the current shell session

For most teams, user-level config suffices — one server, one API key, used by all projects.

Enterprise / On-Prem

If your Waypoint server is behind a VPN, corporate proxy, or firewall:

• Ensure your machine has network access (VPN connected, firewall rules allow egress)
• For proxies: set https_proxy and http_proxy environment variables before launching your agent
• For self-signed certs: ask your admin if the server supports a --insecure flag or cert pinning

Example with proxy:

export https_proxy=http://proxy.yourcompany.com:8080
export http_proxy=http://proxy.yourcompany.com:8080
waypoint connect https://waypoint.internal.yourcompany.com

Next steps

Session Recording — understand what gets captured in each session.

Context Retrieval — dive deeper into how the MCP tools fetch and format history.