> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/ai/developers/connect-your-ide.md). # Connect your IDE Copy-paste setup for Claude Code, Codex, Cursor, Claude Desktop, ChatGPT, Gemini CLI, VS Code and Windsurf — a first prompt and what it returns. You want your AI tool to work on your Norbix backend without writing glue code. Each tool keeps its MCP servers in its own file or command, so the setup differs per tool, but the server is always the same: the Norbix **MCP server** (MCP = Model Context Protocol, the standard way AI tools call outside services) at `https://hub.norbix.ai/v3/account/mcp`. ## How Norbix models it Cloud gives you the right block for your tool: avatar → **Connect your AI** (`/account/connect-ai`). The page has three parts: | Part | What it holds | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Prompt** | A text to paste into any AI tool: where your Hub is, and how to connect. | | **Addresses** | **Hub URL**, **API URL**, **MCP URL** of your installation, each with a copy button. | | **Add Norbix to your tool** | One tab per tool. **Claude Code**, **Codex** and **Cursor** show the **Norbix CLI** first (marked **Recommended**: install, `norbix login`, `norbix ai init`), then **Or connect through MCP**. **Claude Desktop**, **ChatGPT** and **Gemini** show the MCP block only. The tabs `claude-code-ci`, `cursor-ci` and `gemini-ci` hold the API-key versions for unattended runs. | The blocks below are the ones Cloud shows for the managed service. On a self-hosted installation Cloud fills in your own addresses. Two ways to sign in (details: [MCP server](/codemash/ai/developers/mcp-server.md#sign-in-oauth-or-a-key)): * **OAuth** — the default blocks. On first use your browser opens Cloud's consent screen; pick the roles (for example **Viewer** on one project) and press **Allow**. * **API key** — the `-ci` blocks. Put an `nbsu_` key in the `NORBIX_API_KEY` environment variable; the blocks read it from there, so the key never sits in a shared file. ## The blocks {% tabs %} {% tab title="Claude Code" %} **Norbix CLI (recommended).** In your project folder: ```sh npm i -g @norbix.ai/cli norbix login norbix ai init ``` `norbix login` opens Cloud in your browser, you pick the roles and press **Allow**; `norbix ai init` writes `.claude/skills/norbix/SKILL.md` and a short block in `CLAUDE.md`. See [The CLI for agents](/codemash/ai/developers/cli-for-agents.md). **Or connect through MCP:** ```sh claude mcp add --transport http norbix https://hub.norbix.ai/v3/account/mcp ``` Start `claude`, run `/mcp`, pick **norbix** and sign in in the browser. `claude mcp list` shows `! Needs authentication` until you do. **With a key (`claude-code-ci`):** ```sh claude mcp add --transport http norbix https://hub.norbix.ai/v3/account/mcp --header "Authorization: Bearer $NORBIX_API_KEY" ``` `claude mcp list` then shows `✔ Connected`. The shell puts the key's value into the config, so keep this server in the default (local) scope — never add `--scope project`, which writes the key into the shared `.mcp.json`. {% endtab %} {% tab title="Codex" %} **Norbix CLI (recommended):** ```sh npm i -g @norbix.ai/cli norbix login norbix ai init --target agents ``` `--target agents` writes the Norbix block into `AGENTS.md`, which Codex reads. **Or connect through MCP** — add to `~/.codex/config.toml`: ```toml [mcp_servers.norbix] url = "https://hub.norbix.ai/v3/account/mcp" ``` Then sign in once: ```sh codex mcp login norbix ``` `codex mcp list` shows the server with **Auth** `OAuth`. **With a key** (Cloud has no Codex key tab; this is Codex's own setting): ```toml [mcp_servers.norbix] url = "https://hub.norbix.ai/v3/account/mcp" bearer_token_env_var = "NORBIX_API_KEY" ``` {% endtab %} {% tab title="Cursor" %} **Norbix CLI (recommended):** ```sh npm i -g @norbix.ai/cli norbix login norbix ai init --target cursor ``` `--target cursor` writes `.cursor/rules/norbix.mdc`. **Or connect through MCP** — `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for all projects): ```json { "mcpServers": { "norbix": { "url": "https://hub.norbix.ai/v3/account/mcp" } } } ``` Cursor shows **Needs login** next to the server in its MCP settings; click it and allow in the browser. **With a key (`cursor-ci`):** ```json { "mcpServers": { "norbix": { "url": "https://hub.norbix.ai/v3/account/mcp", "headers": { "Authorization": "Bearer ${env:NORBIX_API_KEY}" } } } } ``` {% endtab %} {% tab title="Claude Desktop" %} Claude Desktop's config file starts local servers, so it reaches the remote server through the `mcp-remote` bridge. Add to `claude_desktop_config.json` (Settings → Developer → **Edit Config**): ```json { "mcpServers": { "norbix": { "command": "npx", "args": [ "-y", "mcp-remote", "https://hub.norbix.ai/v3/account/mcp" ] } } } ``` Restart Claude Desktop. The browser opens Cloud's consent screen; it names the tool **MCP CLI Proxy** (the bridge), not Claude Desktop. **With a key** (not in Cloud; `mcp-remote` reads the header from an environment variable of the block): ```json { "mcpServers": { "norbix": { "command": "npx", "args": ["-y", "mcp-remote", "https://hub.norbix.ai/v3/account/mcp", "--header", "Authorization:${NORBIX_AUTH_HEADER}"], "env": { "NORBIX_AUTH_HEADER": "Bearer nbsu_…" } } } } ``` {% endtab %} {% tab title="ChatGPT" %} ChatGPT adds a remote MCP server in its own settings, not from a file (Settings → **Connectors**, developer mode). Cloud shows the standard block so you can copy the address: ```json { "mcpServers": { "norbix": { "url": "https://hub.norbix.ai/v3/account/mcp" } } } ``` Create a connector with that URL and **OAuth** as the authentication; ChatGPT opens Cloud's consent screen. {% endtab %} {% tab title="Gemini CLI" %} Add to `~/.gemini/settings.json` (`httpUrl` = Streamable HTTP): ```json { "mcpServers": { "norbix": { "httpUrl": "https://hub.norbix.ai/v3/account/mcp" } } } ``` In Gemini CLI run `/mcp auth norbix` and allow in the browser. Gemini loads MCP servers only in a **trusted** folder; in an untrusted one `gemini mcp list` shows the server as *Disabled*. **With a key (`gemini-ci`):** ```json { "mcpServers": { "norbix": { "httpUrl": "https://hub.norbix.ai/v3/account/mcp", "headers": { "Authorization": "Bearer $NORBIX_API_KEY" } } } } ``` `gemini mcp list` then shows `✓ norbix … - Connected`. {% endtab %} {% tab title="VS Code" %} Not in Cloud yet. For GitHub Copilot agent mode, add `.vscode/mcp.json`: ```json { "servers": { "norbix": { "type": "http", "url": "https://hub.norbix.ai/v3/account/mcp" } } } ``` Press **Start** above the server in the file; VS Code asks to sign in. **With a key** — VS Code asks for it once and keeps it in its secret store: ```json { "inputs": [ { "type": "promptString", "id": "norbix-key", "description": "Norbix API key (nbsu_…)", "password": true } ], "servers": { "norbix": { "type": "http", "url": "https://hub.norbix.ai/v3/account/mcp", "headers": { "Authorization": "Bearer ${input:norbix-key}" } } } } ``` {% endtab %} {% tab title="Windsurf" %} Not in Cloud yet. Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "norbix": { "serverUrl": "https://hub.norbix.ai/v3/account/mcp" } } } ``` **With a key:** ```json { "mcpServers": { "norbix": { "serverUrl": "https://hub.norbix.ai/v3/account/mcp", "headers": { "Authorization": "Bearer ${env:NORBIX_API_KEY}" } } } } ``` {% endtab %} {% endtabs %} ## A first prompt Ask your tool: > *Show the taxonomies of my Norbix project.* It calls the read tool `get_database_taxonomies`. With exactly one project in its roles it needs no project id. The tool answers like this, and your tool turns it into a list: ```json {"ok":true,"data":{"list":{"items":[{"viewId":"txn_3D8kZTCjIkHkBxFRcUMvHS","taxonomyName":"Genres","taxonomySlug":"genres"},{"viewId":"txn_4z3KlEjT50G0IYYDZl1lRS","taxonomyName":"Authors","taxonomySlug":"authors"}],"hasMore":false,"hasPrevious":false}}} ``` Then try a change: *Create a taxonomy called Publishers.* With **Viewer** the tool answers *Caller is missing required permission 'database:create …'*; with **Administrator** it answers `{"ok":true,"data":{"id":"txn_…"},"env":"TEST",…}`. ## When it does not work | You see | Why | Do this | | ------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | *Needs authentication* / *Needs login* / *Not logged in* | The tool has not signed in yet. | Run the tool's sign-in (`/mcp` in Claude Code, `codex mcp login norbix`, `/mcp auth norbix` in Gemini). | | `401` with a key | The key is wrong, revoked, or the variable is empty. | Check `echo $NORBIX_API_KEY`; issue a new key. | | *Caller is missing required permission …* | The roles you gave do not allow it. | Sign in again and pick a role that allows it. | | `ScopeProjectNotAllowed` | The call named a project outside the service user's roles. | Use that project, or give a role in the other one. | | Too many tools for the model | The model accepts fewer tools than the server lists. | Add `?toolsets=…` to the URL — see [What agents can do](/codemash/ai/developers/what-agents-can-do.md). | | *Refusing to send credentials to non-https token endpoint* (`mcp-remote`) | A self-hosted Hub without TLS. | Serve the Hub over HTTPS. | ## Where you use it * [MCP server](/codemash/ai/developers/mcp-server.md) — address, sign-in, roles * [The CLI for agents](/codemash/ai/developers/cli-for-agents.md) — the recommended way for coding agents * [Read-only keys](/codemash/ai/developers/read-only-keys.md) — the safe roles for an agent * [What agents can do](/codemash/ai/developers/what-agents-can-do.md) — every tool group * Cloud: avatar → **Connect your AI** ([Account](/codemash/cloud/account.md))