# 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:///nests/` (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: | Surface | Who makes the connection | Requirement | |---|---|---| | **Claude Code** (terminal) | **your machine** | your computer just has to reach the host (VPN/localhost fine) | | **claude.ai web, Claude Desktop, ChatGPT** | **Anthropic's servers** | your host must be **publicly resolvable DNS + valid TLS** | **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](#private--on-prem-nests)** at the end. --- ## Claude Code (fastest — one command) ```bash claude mcp add --transport http contextnest \ https:///nests//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: ```json { "mcpServers": { "contextnest": { "type": "http", "url": "https:///nests//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` ```json { "mcpServers": { "contextnest": { "command": "npx", "args": [ "-y", "mcp-remote", "https:///nests//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](#first-the-one-thing-that-trips-everyone-up-reachability)). 1. **Settings → Connectors → Add custom connector** (org owner or directory-permission role). 2. **URL:** `https:///nests//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:///nests//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: ```bash curl -s -X POST https:///nests//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 | Symptom | Cause | Fix | |---|---|---| | `Name or service not known` / DNS error when added to claude.ai | host is internal-only | see [Private / on-prem nests](#private--on-prem-nests) — claude.ai can't reach a private host | | Added the connector but no tools show | restart/reload not done | Claude Code: new session · Desktop: restart app · web: reload page | | "Connected" but answers are vague/empty | you never proved a live pull | run the curl above; confirm real nodes return | | `curl` works but Claude doesn't | key is in the wrong place or the surface can't reach the host | key belongs in config/env; re-check reachability for web surfaces | | claude.ai / ChatGPT connector rejects the key | hosted connectors can't send a Bearer header | they need MCP OAuth sign-in on your server; meanwhile use Claude Code or the Desktop config file | | Key leaked in shell history | passed inline | use the `CONTEXTNEST_API_KEY` env var, not an inline flag; rotate the key | --- ## 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.