> 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/mcp-server.md).

# MCP server

The Norbix MCP server — where it is, how an AI tool signs in to it, and what it may do.

Your AI tool needs a way to reach your Norbix backend that it already understands. **MCP** (Model Context Protocol) is that way: the open standard AI tools use to call outside services as *tools*. Every Norbix installation **is** an MCP server — there is nothing to install or host.

## How Norbix models it

The MCP server is one address on the Hub of your installation:

| Installation              | MCP address                            |
| ------------------------- | -------------------------------------- |
| Managed service           | `https://hub.norbix.ai/v3/account/mcp` |
| Self-hosted or enterprise | `https://<your Hub>/v3/account/mcp`    |

Cloud shows the address of your installation in **Account → Connect your AI → Addresses → MCP URL**, and the Hub lists it in `GET /v3/echo` under `agent.mcpUrl`.

```
Your AI tool ──MCP over HTTPS──▶ Hub /v3/account/mcp ──tool call──▶ a Norbix endpoint
(Claude Code, Cursor,            (OAuth token or                   (with the roles of the
 Codex, ChatGPT, …)               nbsu_ key)                        AI service user)
```

* **Transport:** Streamable HTTP (MCP revision 2025-11-25): `POST` sends one JSON-RPC message, `GET` opens the server's event stream, `DELETE` ends the session. A tool that can only start local (stdio) servers reaches it through a bridge — see [Claude Desktop](/codemash/ai/developers/connect-your-ide.md#claude-desktop).
* **Tools:** every Norbix endpoint that is marked as an AI tool — 418 today, 157 of them only read. Each tool says whether it only reads (`readOnlyHint`). See [What agents can do](/codemash/ai/developers/what-agents-can-do.md).
* **Prompts:** one prompt per Norbix chat profile (`project-creation`, `database-manager`, `campaign-manager`, …), so a tool can load the same working instructions the Norbix assistant uses.
* **Fewer tools:** add `?toolsets=` to the address to load only some groups, for example `…/v3/account/mcp?toolsets=ai:database` (27 tools) or `?toolsets=ai:project-inspect` (146 read tools). Many models accept at most 128 tools in one request, so a filter helps.

## Sign in: OAuth or a key

Every call acts as an **AI service user** — an identity of your account that holds **Membership roles**, like a team member. Its roles decide what the tool may do, exactly as for a person. You can never give it more than you have yourself.

| Way                    | How it works                                                                                                                                                                                                                                                                                                 | Use it for                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| **OAuth** (default)    | The tool gets `401` and finds the sign-in by itself. Your browser opens Cloud's consent screen: you see the tool's name, pick the roles per project (Administrator, Developer, Data Editor, Viewer or one of your own roles) and press **Allow**. The tool gets a one-hour token and refreshes it by itself. | Your own IDE and chat apps.                                 |
| **API key** (`nbsu_…`) | The tool sends `Authorization: Bearer <key>`, read from the `NORBIX_API_KEY` environment variable.                                                                                                                                                                                                           | CI, scripts, servers — anything that runs without a person. |

Without either, the server answers `401`. One AI service user is made per tool and set of roles (named like *Cursor (OAuth 3f9a1c)*); the same tool with the same roles reuses it. **Account → AI service users** in Cloud lists them; removing one signs that tool out at once.

{% hint style="info" %}
Cloud's **AI service users** screen lists and removes service users; it does not create keys. A key for CI comes from the Hub API — see [Read-only keys](/codemash/ai/developers/read-only-keys.md#create-a-key-for-ci).
{% endhint %}

## Scopes: what a tool may do

There is no separate MCP scope. The roles you give decide everything:

| Roles you give                                  | The tool can                                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Viewer** on one project                       | call every read tool of that project; every change is refused with *Caller is missing required permission …* |
| **Data Editor** or **Developer** on one project | read, and change what that role may change                                                                   |
| **Administrator** on one project                | everything in that project                                                                                   |
| an **account** role                             | work in every project that role reaches                                                                      |

* A service user with only **project** roles is pinned to those projects: a call that names another project is refused (`ScopeProjectNotAllowed`), and with exactly one project the tool does not need to name it.
* The tool **lists** all 418 tools whatever its roles; the roles are checked when it **calls** one. See [Read-only keys](/codemash/ai/developers/read-only-keys.md).
* **Environments:** a tool call works in **TEST** unless it names an environment; a change in **PROD** must say `env: "PROD"` on the call.
* **Confirmation:** a tool that sends messages, deletes or changes a lot first answers `requires_confirmation` with the pending action. The agent must ask you, then call again with `confirm: true`.

A confirmation round, as it ran with an Administrator role (`enable_database`):

```json
{"ok":false,"requires_confirmation":true,"pending_action":{"tool":"enable_database","arguments":{"projectId":"pr_3dMEdKCg5DyxGuA4CtzS1F"}},"errors":[{"code":"ConfirmationRequired","message":"'enable_database' changes state and was NOT executed. Get the user's explicit approval for exactly this pending_action, then call the tool again with the same arguments plus confirm: true. …"}],"env":"TEST"}
```

and the second call, with `confirm: true`:

```json
{"ok":true,"data":{},"env":"TEST","dashboardUrl":"<your Cloud address>/projects/test"}
```

Every write answer carries `env` and a `dashboardUrl` to the changed item in Cloud, and every call shows up in [Logs](/codemash/cloud/logs.md).

## The `@norbix.ai/mcp` package (local, key only)

For a tool that can only start local servers, or when you want the generic "search any endpoint" style, there is also an npm package, [`@norbix.ai/mcp`](https://www.npmjs.com/package/@norbix.ai/mcp) (0.2.1). It runs on your machine (stdio, Node.js 18 or newer), signs in with an `nbsu_` key only, and has 24 tools: `norbix_search_endpoints`, `norbix_describe_endpoint` and `norbix_call_endpoint` reach every endpoint of the TypeScript SDK, plus shortcuts such as `norbix_echo`, `norbix_get_database_schemas` and `norbix_find_documents`.

```json
{
  "mcpServers": {
    "norbix": {
      "command": "npx",
      "args": ["-y", "@norbix.ai/mcp"],
      "env": {
        "NORBIX_API_KEY": "nbsu_…",
        "NORBIX_HUB_URL": "https://hub.norbix.ai",
        "NORBIX_PROJECT_ID": "pr_…"
      }
    }
  }
}
```

| Variable                                                             | Required | Meaning                                          |
| -------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| `NORBIX_API_KEY`                                                     | yes      | The `nbsu_` key.                                 |
| `NORBIX_HUB_URL`                                                     | yes      | The Hub address, without `/v3`.                  |
| `NORBIX_PROJECT_ID`                                                  | no       | Default project for calls that need one.         |
| `NORBIX_API_URL`, `NORBIX_ENV`, `NORBIX_REGION`, `NORBIX_ACCOUNT_ID` | no       | Taken from `/echo` or the defaults when not set. |

`norbix-mcp --http --port 3010` runs the same package as a shared Streamable HTTP server (`POST /mcp`, health check `GET /healthz`); each request may then carry its own `Authorization: Bearer` key. Put it behind TLS.

{% hint style="warning" %}
The package's `norbix_get_project` shortcut fails with *Missing path parameter "projectId"*, even when you pass `projectId`. Use `norbix_call_endpoint` with `getProject`, or the Hub MCP server's `get_project` tool.
{% endhint %}

Prefer the Hub MCP server: it signs in with OAuth, its tools are described and ask before big changes, and it needs nothing on your machine.

## Where you use it

* Set it up in your tool: [Connect your IDE](/codemash/ai/developers/connect-your-ide.md)
* Pick the roles: [Read-only keys](/codemash/ai/developers/read-only-keys.md)
* What the tools cover: [What agents can do](/codemash/ai/developers/what-agents-can-do.md)
* The CLI instead of MCP: [The CLI for agents](/codemash/ai/developers/cli-for-agents.md)
* Cloud: Account → **Connect your AI** ([Account](/codemash/cloud/account.md))