> For the complete documentation index, see [llms.txt](https://docs.codemash.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemash.io/ai/mcp-server.md).

# MCP Server

The **Norbix MCP server** — [`@norbix.ai/mcp`](https://www.npmjs.com/package/@norbix.ai/mcp) — lets any AI tool that speaks MCP (Model Context Protocol) work with your Norbix backend: create projects, manage integrations, query databases, manage users, read logs — everything the API key is allowed to do.

It is built on the official [JavaScript / TypeScript SDK](https://github.com/Isidos-co/codemash-docs/tree/main/sdk/javascript-typescript.md) and covers **every** Norbix Hub and API endpoint (\~470) through a small set of tools.

### What you need

1. **A Norbix API key (service user).** In [Norbix Cloud](https://cloud.norbix.ai), open your project → *Membership* → *Service users*. Create a service user, give it a role (for example *Project Administrator* for full access), and issue an API key. The key's permissions decide what the MCP server can do.
2. **Your Norbix Hub endpoint** — `https://hub.norbix.ai`, or your own host on a self-hosted install. The server calls `/echo` on startup to discover the rest (API URL, versions, regions).

### Configuration

All settings are environment variables — the same ones the JS/TS SDK uses:

| Variable            | Required | Meaning                                                                                         |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `NORBIX_API_KEY`    | yes      | Service-user API key (sent as `Authorization: Bearer`).                                         |
| `NORBIX_HUB_URL`    | yes      | Norbix Hub endpoint.                                                                            |
| `NORBIX_PROJECT_ID` | no       | Default project to work in. You can also switch at any time with the `norbix_set_project` tool. |
| `NORBIX_API_URL`    | no       | API endpoint. Discovered from `/echo` when not set.                                             |
| `NORBIX_ENV`        | no       | Project environment (e.g. `DEV`). Default is `PROD`.                                            |
| `NORBIX_REGION`     | no       | Region code (e.g. `nb-eu-germany`).                                                             |

### Run it

MCP clients start the server for you with:

```bash
npx -y @norbix.ai/mcp
```

See [Connect Your AI Tool](/ai/connect-your-ai-tool.md) for ready-to-paste configuration for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and more.

### Tools

**Discovery + generic call — reaches every endpoint:**

* `norbix_search_endpoints` — find endpoints by keyword (`"push template"`, `"invite user"`, …)
* `norbix_describe_endpoint` — full request/response field shapes, nested types, enums
* `norbix_call_endpoint` — execute any endpoint by name with a JSON body
* `norbix_set_project` — set or switch the active project

**Curated shortcuts:** `norbix_echo`, `norbix_get_projects`, `norbix_get_project`, `norbix_create_project`, `norbix_get_project_environments`, `norbix_get_integrations`, `norbix_get_integration`, `norbix_save_integration`, `norbix_test_integration`, `norbix_get_marketplace_integrations`, `norbix_save_marketplace_integration`, `norbix_get_database_schemas`, `norbix_find_documents`, `norbix_get_roles`, `norbix_get_policies`, `norbix_get_logs`, `norbix_list_service_api_keys`.

A typical flow the model follows for anything not curated:

```
norbix_search_endpoints("archive email template")
→ norbix_describe_endpoint("archiveEmailTemplate")
→ norbix_call_endpoint({ name: "archiveEmailTemplate", body: { id: "…" } })
```

### Remote mode (Streamable HTTP)

For a hosted, shared MCP endpoint — useful for teams and for AI clients that only support remote servers:

```bash
NORBIX_HUB_URL=https://hub.norbix.ai norbix-mcp --http --port 3010
```

* Endpoint: `POST http://host:3010/mcp` (stateless Streamable HTTP).
* Each request may carry its own key: `Authorization: Bearer <norbix-api-key>`. This overrides `NORBIX_API_KEY`, so one instance can serve many users.
* Health check: `GET /healthz`.

{% hint style="warning" %}
In `--http` mode, put the server behind TLS and network controls — the `Authorization` header carries the Norbix API key.
{% endhint %}

### Security notes

* The server can do exactly what the API key can do — nothing more. Scope the service user's role to what you need (e.g. read-only roles for analysis).
* Never commit API keys. Use environment variables in the MCP client config.
* Every action is logged — see [Logs & Monitoring](/norbix-cloud/logs.md).

### Source code

<https://github.com/norbix-code/norbix-mcp>