---
title: "Connect an MCP client"
description: "Connect an MCP client to Noxtica: the endpoint, the token credential, scopes, methods, errors and limits, from the published OpenAPI specification."
canonical_url: "https://noxtica.com/docs/api/mcp/"
markdown_url: "https://noxtica.com/docs/api/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.4.0"
site: "Noxtica"
language: "en"
source: markdown
---

# Connect an MCP client

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

## Endpoint

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

### Scope

The MCP server is one HTTPS endpoint, `POST /api/mcp`, on the Backoffice host:
`https://backoffice.noxtica.com` (production). It speaks JSON-RPC 2.0 over a synchronous HTTP POST. It is not part of the
collector API and is not consumed by the SDK family; this file describes the HTTP envelope
and the JSON-RPC methods. The catalogue of tools is **not** listed here: it depends on the
token, so call `tools/list` for the tools your token may use.

### Authentication

Send `Authorization: Bearer mcp_...`, where the token is an MCP token created in the
Backoffice under Integrations & API, MCP tokens (the secret is shown once). The server uses a
static opaque bearer token, **not** OAuth: it sends no `WWW-Authenticate` challenge and
exposes no OAuth metadata, so configure your MCP client with a custom `Authorization`
header. A token lives at most 90 days and also expires after 90 days without use. A revoked,
expired or unknown token gets HTTP `401`.

A token is either a *read* token or a *write* token and carries scopes. Scopes are the
ceiling of what a token can do: `tools/list` shows only the tools a token's scopes and tool
allowlist permit, and a tool outside them answers JSON-RPC error `-32001` (a tool that does
not exist for the token answers `-32002`). A write token can only *plan* a management
change; it can never apply one: a person approves every plan in the Backoffice.

### Methods

| Method | Purpose |
|---|---|
| `initialize` | Server information and capabilities. |
| `tools/list` | The tools this token may call, with their input schemas. |
| `tools/call` | Call one tool: `params: {"name": "...", "arguments": {...}}`. The result is one text content item holding JSON. |
| `resources/list`, `resources/templates/list`, `resources/read` | Public-content resources, available only for tokens that are allowed to read them; otherwise `-32601`. |

The protocol version answered by `initialize` is `2024-11-05`. A client that asks for
`2025-03-26` in `initialize.params.protocolVersion` gets that version when streamable
transport is enabled for the deployment; the server then also answers the same JSON-RPC
response as a single `text/event-stream` message when the request carries
`Accept: text/event-stream`. Otherwise the answer is always a plain JSON body.

### Errors

Transport-level failures use the HTTP status and a small JSON body:
`401 {"error":"unauthorized"}`, `404 {"error":"not_found"}` (MCP is not enabled for the
deployment), `429 {"error":"rate_limited"}` and `500 {"error":"internal_error"}`. Everything
else is a JSON-RPC error carried in an HTTP `200` body, including an unparseable body
(`-32700`). Branch on the numeric `error.code`; see `JsonRpcError`.

### Rate limits and limits

Each token has a request limit; a request over it answers `429` with `Retry-After` and the
headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix seconds)
and `X-RateLimit-Bucket`, which are also sent on successful responses of this endpoint.
`tools/call` and resource reads are additionally limited to 60 calls per 60 seconds per
token; going over answers `-32004` with `error.data.retryAfterSeconds`. A monthly query
allowance applies to tool calls and resource reads (`-32003` when used up, `-32005` when the
plan does not include MCP). A serialized tool result may be at most 200 KB; a larger one
answers `-32602`, so lower the `limit` argument of the tool. The request body may be at most
1 MB.

## Operations

The full request and response description of each operation is in the [MCP server](https://noxtica.com/docs/api/reference/mcp/) reference.

| Operation | Request | Summary |
| --- | --- | --- |
| [`mcpJsonRpc`](https://noxtica.com/docs/api/reference/mcp/#mcpJsonRpc) | `POST /api/mcp` | Send one MCP JSON-RPC request |

_This page is generated from the Noxtica OpenAPI specification release `v0.4.0`: `kyc.yaml` version `1.2.0-2026-10-27` (SHA-256 `c91a695cfde0`), `mcp.yaml` version `0.1.0-2026-10-27` (SHA-256 `1a4875efa736`), `pulse.yaml` version `0.9.0-2026-10-27` (SHA-256 `95196a58bb5b`), `v1.yaml` version `1.3.0-2026-10-27` (SHA-256 `3fd15257a022`). Do not edit it by hand._