Connect ContextNest to Claude

Your nest is a governed, cited knowledge graph. This page shows how to connect it to Claude on every surface, and — just as important — how to prove the connection is live before you trust an answer.

The golden rule: don't believe you're connected until you've pulled real data. Every path below ends with a one-line proof that returns your actual node count and titles. If it returns nothing, you're not connected — stop and check the troubleshooting section, don't keep going.

What you need

• Your nest URL — https://<your-host>/nests/<nest-id> (e.g. https://nest.promptowl.ai/nests/ad8fe978-…).
• Your API key (cnst_…). Get it from the Connect modal in your nest.
• Put the key in a config file or an environment variable — never paste it into a chat.

First, the one thing that trips everyone up: reachability

There are two kinds of Claude surface, and they reach your nest differently:

If your nest host is internal-only (e.g. resolves only on a company VPN), it will work great from Claude Code but can never be added to claude.ai / Desktop / ChatGPT — their connection is made from Anthropic's side, and Anthropic can't resolve a private hostname. If that's you, see Private / on-prem nests at the end.

Claude Code (fastest — one command)

claude mcp add --transport http contextnest \
  https://<your-host>/nests/<nest-id>/mcp \
  --header "Authorization: Bearer $CONTEXTNEST_API_KEY"

(Set export CONTEXTNEST_API_KEY='cnst_…' first so the key isn't in your shell history.)

Prefer it version-controlled for a team? Add to .mcp.json in your repo root instead:

{
  "mcpServers": {
    "contextnest": {
      "type": "http",
      "url": "https://<your-host>/nests/<nest-id>/mcp",
      "headers": { "Authorization": "Bearer ${CONTEXTNEST_API_KEY}" }
    }
  }
}

Restart note: if you add the server mid-session, its tools won't appear until you start a fresh claude session. A new session reads .mcp.json automatically.

Claude Desktop

Claude Desktop connects to a remote nest through the mcp-remote bridge. Edit your config file:

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

{
  "mcpServers": {
    "contextnest": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://<your-host>/nests/<nest-id>/mcp",
        "--header", "Authorization: Bearer ${CONTEXTNEST_API_KEY}"
      ],
      "env": { "CONTEXTNEST_API_KEY": "cnst_…" }
    }
  }
}

Restart Claude Desktop after saving — tools only load on restart.

claude.ai (web) & Claude Desktop — Custom Connector

Requires your host to be publicly reachable + TLS (see reachability).

1. Settings → Connectors → Add custom connector (org owner or directory-permission role).
2. URL: https://<your-host>/nests/<nest-id>/mcp
3. Transport: Streamable HTTP (or SSE).
4. Auth: hosted connectors sign in with OAuth. They can't send a custom Authorization: Bearer cnst_… header, so pasting a cnst_ key here won't authenticate. Your nest server must have MCP OAuth sign-in enabled; until it does, use Claude Code or the Claude Desktop config file above, which send the key from your own machine.
5. Reload the page — tools appear on your next message, not before.

ChatGPT

Same shape as the custom connector: add ContextNest's MCP URL (https://<your-host>/nests/<nest-id>/mcp) in ChatGPT's connector/MCP settings. Like claude.ai, it signs in with OAuth rather than a pasted cnst_ key, so your server needs MCP OAuth sign-in enabled. The public DNS + TLS requirement applies here too — the connection is made from OpenAI's servers.

Prove it's live (do this on every surface)

Before trusting any answer, confirm a real pull. From a terminal that can reach the host:

curl -s -X POST https://<your-host>/nests/<nest-id>/context \
  -H "Authorization: Bearer $CONTEXTNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selector":"type:document","hops":1,"max_tokens":2000}'

You should see real node content come back. In Claude itself, ask it to list a few node titles and a count — if it can't, it isn't actually connected yet (usually a missing restart/reload).

Troubleshooting

Private / on-prem nests

If your nest host isn't public (VPN-only, internal DNS), you have three options:

1. Public TLS gateway — front the nest with a publicly resolvable hostname + valid cert so claude.ai/Desktop/ChatGPT can reach it.
2. MCP Tunnels — connect a private-network nest to claude.ai without exposing it publicly.
3. Claude Code only — the local surface works over your VPN/localhost with no public host needed.