openapi: 3.0.3
info:
  title: naturali.ai — MCP Servers API
  version: 1.0.0
  description: >
    MCP servers, scoped to a project. A server is a chosen set of the
    project's tools, each `(tool_id, action)` pair exposed as one MCP tool, so an MCP client such as Claude, ChatGPT or Cursor
    reaches them without holding a credential of the project.

    **Context.** `context` on the server and on each caller (an `allowlist`
    entry, a `header` key, a tenant issuer's `context_claims`) is merged into
    the `tool_context` of every call the server makes. Values are write-only:
    a read returns `context_keys`. Keys starting with `naturali_` are set by
    the platform only: `naturali_mcp_server_id` on every call, and for an
    `oauth` caller `naturali_caller_id`, `naturali_caller_issuer` and, when
    known and verified, `naturali_caller_email`.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: '{baseUrl}'
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: McpServers
    description: Serve a chosen set of a project's tools as an MCP server.
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/mcp-servers:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [McpServers]
      summary: List MCP servers
      description: The project's MCP servers, newest first.
      operationId: listMcpServers
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of MCP servers.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/McpServer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags: [McpServers]
      summary: Create an MCP server
      description: >
        Each item of `tools` is checked against the tool it names: one of the
        project's, else `400`. `action` is required,
        and must be one of the tool's available actions, when the tool declares
        `actions`; otherwise it is ignored and stored as `null`. A tool whose
        definition reads `{{context:naturali_caller_…}}` is refused unless
        `auth.type` is `oauth`.

        `daily_call_limit` is required when `auth` is `none`.
      operationId: createMcpServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpServerCreate'
      responses:
        '201':
          description: MCP server created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/McpServerUpstreamUnavailable'
  /v1/projects/{project_id}/mcp-servers/{mcp_server_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/McpServerId'
    get:
      tags: [McpServers]
      summary: Get an MCP server
      description: >-
        The server, with the keys of its context (values are never returned)
        and the items it cannot serve now.
      operationId: getMcpServer
      responses:
        '200':
          description: The MCP server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [McpServers]
      summary: Update an MCP server
      description: >
        A field sent replaces the stored one, `tools`, `context` and `auth`
        whole; `null` clears an optional field. The result is checked as on
        create. Changing `auth.type` away from `header` deletes the server's
        keys.
      operationId: updateMcpServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpServerUpdate'
      responses:
        '200':
          description: MCP server updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/McpServerUpstreamUnavailable'
    delete:
      tags: [McpServers]
      summary: Delete an MCP server
      description: Removes the server, its keys and its call log.
      operationId: deleteMcpServer
      responses:
        '204':
          description: MCP server deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/keys:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/McpServerId'
    get:
      tags: [McpServers]
      summary: List MCP server keys
      description: The server's keys, newest first. The secret is not returned.
      operationId: listMcpServerKeys
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of keys.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/McpServerKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags: [McpServers]
      summary: Create an MCP server key
      description: >
        A key confined to this server, for a server whose `auth.type` is
        `header`. The response carries `key`; **this is the only time it is
        returned.** `idempotency_key` is refused.
      operationId: createMcpServerKey
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpServerKeyCreate'
      responses:
        '201':
          description: Key created. The secret is included, once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerKeyWithSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/McpServerAuthNotHeader'
  /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/usage:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/McpServerId'
    get:
      tags: [McpServers]
      summary: List MCP server usage
      description: >-
        The server's call log, newest day first: one row per UTC day, caller
        and item, with its calls and how many failed. Arguments are not
        stored. Today's `count` summed over the rows is what
        `daily_call_limit` is checked against.
      operationId: listMcpServerUsage
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of usage rows.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/McpServerUsage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/keys/{key_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/McpServerId'
      - $ref: '#/components/parameters/McpServerKeyId'
    delete:
      tags: [McpServers]
      summary: Revoke an MCP server key
      description: Deletes the key; a client holding it can no longer connect.
      operationId: deleteMcpServerKey
      responses:
        '204':
          description: Key revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: >-
        A connected app's OAuth access token, issued by this API's authorization
        server (discovery: /.well-known/oauth-authorization-server). Its one scope
        carries every operation, confined to the projects the user chose when
        approving the app.
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1
        or not an integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `next_cursor`; omit it for the first page. A cursor
        this list did not issue is `400`.
      schema:
        type: string
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    McpServerId:
      name: mcp_server_id
      in: path
      required: true
      description: MCP server public ID (mcps_ prefix).
      schema:
        type: string
        example: mcps_V1StGXR8Z5jdHi6B
    McpServerKeyId:
      name: key_id
      in: path
      required: true
      description: MCP server key public ID (mcpk_ prefix).
      schema:
        type: string
        example: mcpk_V1StGXR8Z5jdHi6B
  responses:
    Forbidden:
      description: >-
        The credential is scoped to a different project, or the caller's role in
        the project does not carry this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    McpServerUpstreamUnavailable:
      description: >-
        The upstream runtime could not be reached or answered unexpectedly
        (`UPSTREAM_UNAVAILABLE`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    McpServerAuthNotHeader:
      description: >-
        The server's `auth.type` is not `header` (`MCP_SERVER_AUTH_NOT_HEADER`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Page:
      type: object
      description:
        One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: >-
            Structured error. Every error response uses this shape, so `code` can
            be read without first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: '^[A-Z][A-Z0-9_]*$'
              description: >-
                Machine-readable error code, UPPER_SNAKE whether naturali or the
                runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: >-
                What to do about it, naming the routes of this API to call. For
                people and agents; it may change, so branch on `code`.
              example: >-
                Use a credential whose scope includes this action, or ask a
                project `admin` or `owner` to act; the caller's role or key
                excludes it.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Structured context, such as the `resource` and `limit` of a
                `PLAN_LIMIT_REACHED`.
    McpContext:
      type: object
      additionalProperties:
        type: string
      description: >-
        Literal string values merged into each call's `tool_context`. Keys are
        header names, unique ignoring case; `naturali_*` is refused.
      example:
        tenant: acme
    McpContextKeys:
      type: array
      items:
        type: string
      description: The keys of the stored context; values are never returned.
      example: [tenant]
    McpServerToolItem:
      type: object
      required: [tool_id]
      properties:
        tool_id:
          type: string
          x-naturali-ref: tools
          description: A tool of the project.
          example: tool_V1StGXR8Z5jdHi6B
        action:
          type: string
          nullable: true
          description: >-
            Required when the tool declares `actions`, and one of them; ignored
            otherwise.
          example: search-knowledge
        name:
          type: string
          nullable: true
          pattern: '^[A-Za-z0-9_.-]{1,128}$'
          description: The name MCP clients see, unique in the server.
          example: search_docs
        description:
          type: string
          nullable: true
          maxLength: 2000
          description: The description MCP clients see.
          example: Search the product documentation.
    McpServerToolEntry:
      type: object
      required: [tool_id, action, name, description]
      properties:
        tool_id:
          type: string
          x-naturali-ref: tools
          example: tool_V1StGXR8Z5jdHi6B
        action:
          type: string
          nullable: true
          example: search-knowledge
        name:
          type: string
          nullable: true
          example: search_docs
        description:
          type: string
          nullable: true
          example: Search the product documentation.
    McpServerAuthWrite:
      type: object
      required: [type]
      description: >-
        Who may connect. `oauth` without `issuer` signs callers in by naturali
        login, with `mode` `members` (project members) or `allowlist` (the
        listed emails, verified); `oauth` with `issuer` accepts tokens of the
        tenant's authorization server; `header` (holders of a key from
        [`POST /v1/projects/{project_id}/mcp-servers/{mcp_server_id}/keys`](/docs/api/mcp-servers/create-mcp-server-key),
        sent in `header_name`, default `Authorization`); `none` (anyone).
      properties:
        type:
          type: string
          enum: [oauth, header, none]
          example: oauth
        mode:
          type: string
          enum: [members, allowlist]
          description: '`oauth` without `issuer` only, required.'
          example: allowlist
        issuer:
          type: string
          format: uri
          description: >-
            The tenant's authorization server (an `https` issuer identifier).
            A token is accepted when its signature verifies against `jwks_uri`
            and its `iss` is this value, `exp` is in the future, `aud` names
            the server's `url`, and its `scope` holds every one of `scopes`.
          example: https://login.acme.com
        jwks_uri:
          type: string
          format: uri
          description: Required with `issuer`; an `https` URL. Keys signing `RS256`, `ES256` or `EdDSA`.
          example: https://login.acme.com/.well-known/jwks.json
        scopes:
          type: array
          maxItems: 20
          description: With `issuer`. Scopes every token must carry; default none.
          items:
            type: string
          example: [mcp]
        context_claims:
          type: object
          additionalProperties:
            type: string
          description: >-
            With `issuer`. Each key, a `tool_context` key as in `context`,
            takes the string value of the token claim it names; a claim absent
            or not a string sets nothing.
          example:
            client_id: acme_client
        allowlist:
          type: array
          description: '`mode: allowlist` only, required and non-empty.'
          items:
            type: object
            required: [email]
            properties:
              email:
                type: string
                format: email
                example: ana@acme.com
              context:
                $ref: '#/components/schemas/McpContext'
        header_name:
          type: string
          description: '`header` only. Default `Authorization`, read as `Bearer <key>`.'
          example: Authorization
    McpServerAuth:
      type: object
      description: Who may connect. See [Auth](/docs/modules/mcp-servers#auth).
      required: [type]
      properties:
        type:
          type: string
          enum: [oauth, header, none]
          example: oauth
        mode:
          type: string
          enum: [members, allowlist]
          example: allowlist
        issuer:
          type: string
          example: https://login.acme.com
        jwks_uri:
          type: string
          example: https://login.acme.com/.well-known/jwks.json
        scopes:
          type: array
          items:
            type: string
          example: [mcp]
        context_claims:
          type: object
          additionalProperties:
            type: string
          example:
            client_id: acme_client
        allowlist:
          type: array
          items:
            type: object
            required: [email, context_keys]
            properties:
              email:
                type: string
                example: ana@acme.com
              context_keys:
                $ref: '#/components/schemas/McpContextKeys'
        header_name:
          type: string
          example: Authorization
    McpServer:
      type: object
      required:
        [
          id,
          project_id,
          url,
          name,
          title,
          instructions,
          logo,
          website_url,
          tools,
          tool_mode,
          context_keys,
          auth,
          daily_call_limit,
          created_at,
          updated_at,
        ]
      properties:
        id:
          type: string
          description: Public MCP server ID (mcps_ prefix).
          example: mcps_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: "The owning project."
          x-naturali-ref: project
          example: proj_V1StGXR8Z5jdHi6B
        url:
          type: string
          description: >-
            Where MCP clients connect (Streamable HTTP). An `oauth` server
            answers `401` without a token, naming its OAuth protected resource
            metadata (RFC 9728) at
            `/.well-known/oauth-protected-resource/servers/{id}` on the same
            host, which names the issuer to sign in at.
          example: https://mcp.naturali.ai/servers/mcps_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: '`serverInfo.name`.'
          example: clareza
        title:
          type: string
          nullable: true
          description: '`serverInfo.title`.'
          example: Clareza
        instructions:
          type: string
          nullable: true
          description: '`instructions` in the `initialize` result.'
          example: Narrate scripts and render videos.
        logo:
          type: string
          nullable: true
          description: '`serverInfo.icons`; an `https` URL.'
          example: https://example.com/logo.png
        website_url:
          type: string
          nullable: true
          description: '`serverInfo.websiteUrl`.'
          example: https://example.com
        tools:
          type: array
          description: "`tool_id`, `action`, and the `name` and `description` clients see; at most 100."
          items:
            $ref: '#/components/schemas/McpServerToolEntry'
        tool_mode:
          type: string
          enum: [list, compact]
          description: >-
            `list` lists every tool; `compact` serves `search`, `describe` and
            `call` over them.
          example: list
        context_keys:
          $ref: '#/components/schemas/McpContextKeys'
        auth:
          $ref: '#/components/schemas/McpServerAuth'
        daily_call_limit:
          type: integer
          description: "Calls per UTC day. Required when `auth` is `none`."
          nullable: true
          example: 1000
        created_at:
          type: string
          format: date-time
          example: '2026-11-01T00:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-11-01T00:00:00.000Z'
    McpServerDetail:
      allOf:
        - $ref: '#/components/schemas/McpServer'
        - type: object
          required: [unavailable_tools]
          properties:
            unavailable_tools:
              type: array
              description: >-
                Items the server does not serve now: the tool is gone, or the
                action is no longer one of its available actions. `tools/list`
                leaves them out and a call to one is a tool error. Returned by get,
                create and update, not by list.
              items:
                $ref: '#/components/schemas/McpServerToolEntry'
    McpServerCreate:
      type: object
      required: [name, auth]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: clareza
        title:
          type: string
          nullable: true
          maxLength: 200
          example: Clareza
        instructions:
          type: string
          nullable: true
          maxLength: 10000
          example: Narrate scripts and render videos.
        logo:
          type: string
          nullable: true
          example: https://example.com/logo.png
        website_url:
          type: string
          nullable: true
          example: https://example.com
        tools:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/McpServerToolItem'
        tool_mode:
          type: string
          enum: [list, compact]
          default: list
          example: list
        context:
          $ref: '#/components/schemas/McpContext'
        auth:
          $ref: '#/components/schemas/McpServerAuthWrite'
        daily_call_limit:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            Tool calls per UTC day, over every caller; past it a call is `429
            QUOTA_EXCEEDED`. Required for `none`.
          example: 1000
    McpServerUpdate:
      type: object
      description: At least one field is required.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: clareza
        title:
          type: string
          nullable: true
          example: Clareza
        instructions:
          type: string
          nullable: true
          example: Narrate scripts and render videos.
        logo:
          type: string
          nullable: true
          example: https://example.com/logo.png
        website_url:
          type: string
          nullable: true
          example: https://example.com
        tools:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/McpServerToolItem'
        tool_mode:
          type: string
          enum: [list, compact]
          example: compact
        context:
          $ref: '#/components/schemas/McpContext'
        auth:
          $ref: '#/components/schemas/McpServerAuthWrite'
        daily_call_limit:
          type: integer
          nullable: true
          minimum: 1
          example: 1000
    McpServerKey:
      type: object
      required:
        [
          id,
          project_id,
          mcp_server_id,
          name,
          key_prefix,
          context_keys,
          created_at,
        ]
      properties:
        id:
          type: string
          description: Public key ID (mcpk_ prefix).
          example: mcpk_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: "The owning project."
          x-naturali-ref: project
          example: proj_V1StGXR8Z5jdHi6B
        mcp_server_id:
          type: string
          description: "The server the key opens."
          example: mcps_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: "Label."
          nullable: true
          example: claude desktop
        key_prefix:
          type: string
          description: The start of the key, to tell keys apart.
          example: nat_mcp_V1St
        context_keys:
          $ref: '#/components/schemas/McpContextKeys'
        created_at:
          type: string
          format: date-time
          example: '2026-11-01T00:00:00.000Z'
    McpServerKeyWithSecret:
      allOf:
        - $ref: '#/components/schemas/McpServerKey'
        - type: object
          required: [key]
          properties:
            key:
              type: string
              description: The key (nat_mcp_ prefix), returned only by the create response.
              example: nat_mcp_V1StGXR8Z5jdHi6BQe4kL2mN
    McpServerUsage:
      type: object
      required: [day, caller, tool_id, action, count, failures]
      properties:
        day:
          type: string
          format: date
          description: The UTC day.
          example: '2026-11-02'
        caller:
          type: object
          required: [type, id]
          properties:
            type:
              type: string
              enum: [key, account, subject, anonymous]
              description: >-
                `key` on a `header` server, `account` on an `oauth` server by
                naturali login, `subject` on one with `auth.issuer`,
                `anonymous` on a `none` one.
              example: key
            id:
              type: string
              nullable: true
              description: >-
                The key's ID (mcpk_ prefix), the naturali account's, or the
                token's `sub`; `null` for `anonymous`.
              example: mcpk_V1StGXR8Z5jdHi6B
        tool_id:
          type: string
          x-naturali-ref: tools
          example: tool_V1StGXR8Z5jdHi6B
        action:
          type: string
          nullable: true
          example: search-knowledge
        count:
          type: integer
          description: Calls that reached the tool.
          example: 42
        failures:
          type: integer
          description: Of `count`, the calls whose tool call failed.
          example: 1
    McpServerKeyCreate:
      type: object
      properties:
        name:
          type: string
          nullable: true
          maxLength: 100
          example: claude desktop
        context:
          $ref: '#/components/schemas/McpContext'
