---
title: "MCP server"
description: "Connect an AI assistant or your own code to your workspace through the Model Context Protocol with a scoped token."
canonical_url: "https://noxtica.com/docs/api/reference/mcp/"
markdown_url: "https://noxtica.com/docs/api/reference/mcp/index.md"
last_updated: 2026-10-27
published: 2026-10-27
section: "server-apis"
section_title: "Server APIs"
openapi_release: "v0.4.0"
openapi_spec_version: "0.1.0-2026-10-27"
site: "Noxtica"
language: "en"
source: markdown
---

# MCP server

Connect an AI assistant or your own code to your workspace through the Model Context Protocol with a scoped token.

One endpoint, `POST /api/mcp` on `https://backoffice.noxtica.com` (production), authenticated with an MCP token (`Authorization: Bearer mcp_...`) created under Integrations & API, MCP tokens. The token's scopes decide which tools it can call; call `tools/list` for the current catalogue.

| Environment | Base URL |
| --- | --- |
| Production | `https://backoffice.noxtica.com` |

Credential: `McpTokenAuth`. See [Authentication](https://noxtica.com/docs/api/authentication/).

## Send one MCP JSON-RPC request {#mcpJsonRpc}

`POST /api/mcp`

Sends one JSON-RPC 2.0 request and returns one JSON-RPC 2.0 response. Set
`Content-Type: application/json`. Notifications and batches are not supported: send one
request object with a `method` and, for calls that expect an answer, an `id`.

The HTTP status is `200` for every JSON-RPC outcome, including errors, except for the
transport failures `401`, `404`, `429` and `500`.

**Authentication:** Bearer token (`McpTokenAuth`).

### Request body

Content type `application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | string | Yes | Allowed values: `2.0`. |
| `id` | string or integer, nullable | No | Echoed in the response. Omit only for requests where you do not need the answer correlated. |
| `method` | string | Yes | One of `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`. |
| `params` | object | No | Method parameters. `tools/call` takes `{name, arguments}`; `resources/read` takes `{uri}`; `initialize` may carry `protocolVersion`. |

### Responses

| Status | Meaning | Error codes | Content |
| --- | --- | --- | --- |
| `200` | A JSON-RPC response: `result` on success or `error` on failure (the HTTP status is `200` in both cases). With streamable transport negotiated and `Accept: text/event-stream`, the same object is sent as one `text/event-stream` `message` event. |  | `application/json` JsonRpcResponse, `text/event-stream` |
| `401` | `unauthorized` — the `Authorization` header is missing or the token is unknown, revoked or expired. The body is identical for every cause. | `unauthorized` | `application/json` McpHttpError |
| `404` | `not_found` — the MCP server is not enabled for this deployment; the body is the same as for a path that does not exist. | `not_found` | `application/json` McpHttpError |
| `429` | `rate_limited` — the token exceeded its request limit. Wait `Retry-After` seconds. | `rate_limited` | `application/json` McpHttpError |
| `500` | `internal_error` — an unexpected server error. Retry with backoff. | `internal_error` | `application/json` McpHttpError |

**Response headers**

| Status | Header | Type | Description |
| --- | --- | --- | --- |
| `200` | `X-RateLimit-Bucket` | string | The name of the rate-limit bucket (`mcp`). |
| `200` | `X-RateLimit-Limit` | integer | The request limit of the token's bucket. |
| `200` | `X-RateLimit-Remaining` | integer | Requests left in the current window. |
| `200` | `X-RateLimit-Reset` | integer | Unix time, in seconds, at which the window resets. |
| `429` | `Retry-After` | integer | Seconds until the token may call again. |
| `429` | `X-RateLimit-Bucket` | string | The name of the rate-limit bucket (`mcp`). |
| `429` | `X-RateLimit-Limit` | integer | The request limit of the token's bucket. |
| `429` | `X-RateLimit-Remaining` | integer | Requests left in the current window. |
| `429` | `X-RateLimit-Reset` | integer | Unix time, in seconds, at which the window resets. |

**Response fields** (`200`, `application/json`)

| Field | Type | Always returned | Description |
| --- | --- | --- | --- |
| `jsonrpc` | string | Yes | Allowed values: `2.0`. |
| `id` | string or integer, nullable | Yes |  |
| `result` | any | No | Present on success. For `tools/call`: `{content: [{type: "text", text: "<JSON>"}], isError: false}`. For `tools/list`: `{tools: [...]}`. For `initialize`: `{protocolVersion, serverInfo, capabilities}`. |
| `error` | object (JsonRpcError) | No | `code` values: `-32700` the body is not valid JSON; `-32600` no `method`; `-32601` unknown method; `-32602` invalid parameters, or the result exceeds 200 KB; `-32603` the tool or resource failed; `-32001` the token's scopes or tool list do not allow the tool (`data.requiredScope` names the missing scope); `-32002` tool not found for this token; `-32003` the monthly query allowance is used up; `-32004` too many tool calls (`data.retryAfterSeconds`, `data.limit`, `data.windowSeconds`); `-32005` MCP is not included in the plan; `-32006` resource not found. |
| `error.code` | integer | Yes | Allowed values: `-32700`, `-32600`, `-32601`, `-32602`, `-32603`, `-32001`, `-32002`, `-32003`, `-32004`, `-32005`, `-32006`. |
| `error.message` | string | Yes |  |
| `error.data` | object | No | Optional structured detail, for example `requiredScope` or `retryAfterSeconds`. |
| `error.data.requiredScope` | string | No |  |
| `error.data.retryAfterSeconds` | integer | No |  |
| `error.data.limit` | integer | No |  |
| `error.data.windowSeconds` | integer | No |  |
| `error.data.code` | string | No |  |

**Response example** (`200`)

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error"
  }
}
```

### Example request

**curl**

```bash
curl -X POST "https://backoffice.noxtica.com/api/mcp" \
  -H "Authorization: Bearer $NOXTICA_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_alerts",
    "arguments": {
      "limit": 25
    }
  }
}'
```

**Node.js** (global `fetch`, Node 18 or later)

```js
const response = await fetch('https://backoffice.noxtica.com/api/mcp', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_MCP_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'list_alerts',
      arguments: {
        limit: 25,
      },
    },
  }),
});
console.log(response.status, await response.text());
```

**Python** (standard library)

```python
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://backoffice.noxtica.com/api/mcp",
    data=json.dumps({
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": "list_alerts",
            "arguments": {
                "limit": 25,
            },
        },
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_MCP_TOKEN']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())
```

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`). Do not edit it by hand._