> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an MCP server

> Registers an org-level MCP server.  Secret values supplied in `secrets` are stored write-only and never returned.

<sub>Scope: `plugins:write`</sub>



## OpenAPI

````yaml /openapi/openapi.json post /v3/organizations/{orgId}/mcp-servers
openapi: 3.1.0
info:
  title: Ara API
  version: 3.0.0
  description: >-
    The Ara HTTP API. Drive cloud software-engineering agents: open sessions
    against your repositories, stream their work, and manage the secrets,
    knowledge, skills, and automations they run with.


    All requests authenticate with an `ara_` API key sent as a bearer token.
    Every resource is scoped to an organization; resolve your `org_id` once with
    `GET /v3/self`.
servers:
  - url: https://api.ara.so
security:
  - araApiKey: []
tags:
  - name: Account
    description: Verify a key and resolve the organization it belongs to.
  - name: Sessions
    description: >-
      A session is one run of an agent against a repository: it reproduces the
      task, writes the code, verifies it, and opens a pull request or merge
      request.
  - name: Secrets
    description: >-
      Encrypted credentials injected into the agent's sandbox. Write-only:
      values can be set but never read back.
  - name: Knowledge
    description: Durable notes the agent consults while it works.
  - name: Memory
    description: >-
      Editable repository notes that are projected into native memory; generated
      memory remains read-only.
  - name: Skills
    description: Reusable instruction bundles that activate for matching agent tasks.
  - name: Automations
    description: Recurring or one-time triggers that open sessions on a timetable.
  - name: Change Request Reviews
    description: >-
      Automated senior-engineer reviews posted on pull requests and merge
      requests.
  - name: Repositories
    description: Connected repositories, their indexing state, and generated wikis.
  - name: Git Connections
    description: Linked source-control accounts and the repositories they expose.
  - name: Consumption
    description: 'Billing-aligned usage: daily consumption and billing cycles.'
  - name: Metrics
    description: Aggregate analytics over sessions, change requests, and usage.
  - name: Audit Logs
    description: An append-only record of changes made within the organization.
  - name: Organizations
    description: The top-level tenant. Create, read, update, and delete organizations.
  - name: Members
    description: People in an organization and their pending invites.
  - name: Service Users
    description: Machine principals that own API keys for headless access.
  - name: Roles
    description: Role assignments that govern what each member can do.
  - name: Attachments
    description: >-
      Files uploaded to the organization and shared with sessions, downloaded
      via short-lived signed URLs.
  - name: Guardrails
    description: >-
      Per-repository automation limits and the violations recorded when a limit
      is hit.
  - name: MCP Servers
    description: >-
      Org-level Model Context Protocol servers exposed to the agent. Secret
      values are write-only.
  - name: Settings
    description: 'Organization configuration: namespaced settings and the run tag policy.'
  - name: Blueprints
    description: >-
      Read-only declarative manifests of an organization's agents (identity, run
      config, triggers, suite), with credentials redacted.
  - name: IP Access List
    description: >-
      Source-network allow-list that, when enabled, restricts the organization's
      API surface to a set of CIDR ranges.
  - name: Groups
    description: Manually-curated member groups carrying optional per-day resource limits.
paths:
  /v3/organizations/{orgId}/mcp-servers:
    parameters:
      - $ref: '#/components/parameters/orgId'
    post:
      tags:
        - MCP Servers
      summary: Create an MCP server
      description: >-
        Registers an org-level MCP server.  Secret values supplied in `secrets`
        are stored write-only and never returned.


        <sub>Scope: `plugins:write`</sub>
      operationId: createMcpServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpServerInput'
      responses:
        '201':
          description: The created MCP server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - araApiKey:
            - plugins:write
components:
  parameters:
    orgId:
      name: orgId
      in: path
      required: true
      description: Organization id or slug. Resolve it with `GET /v3/self`.
      schema:
        type: string
  schemas:
    McpServerInput:
      type: object
      properties:
        name:
          type: string
        transport:
          type: string
          enum:
            - http
            - stdio
            - sse
        icon:
          type: string
        description:
          type: string
        url:
          type: string
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        headers:
          type: object
          additionalProperties:
            type: string
        auth_type:
          type: string
          enum:
            - none
            - oauth
            - bearer
        secrets:
          type: object
          additionalProperties:
            type: string
          description: >-
            Write-only. Secret values to store for this server. Never returned
            in any response.
        enabled:
          type: boolean
      required:
        - name
        - transport
      description: >-
        Request body for creating or updating an MCP server. On update, every
        property is optional and only the supplied fields change.
    McpServer:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        icon:
          type:
            - string
            - 'null'
        description:
          type: string
        source:
          type: string
        transport:
          type: string
          enum:
            - http
            - stdio
            - sse
        url:
          type:
            - string
            - 'null'
        command:
          type:
            - string
            - 'null'
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        headers:
          type: object
          additionalProperties:
            type: string
        auth_type:
          type: string
          enum:
            - none
            - oauth
            - bearer
        secret_names:
          type: array
          items:
            type: string
          description: >-
            The names of the secrets configured for this server. Secret values
            are write-only and are never returned.
        access:
          type: string
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      description: >-
        An org-level MCP server. Secret values are write-only and are never
        returned; only `secret_names` lists which secrets are set.
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: prompt_required
    Forbidden:
      description: The key lacks the required scope or role.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: forbidden
  securitySchemes:
    araApiKey:
      type: http
      scheme: bearer
      bearerFormat: ara_<hex>
      description: >-
        Your `ara_` API key from Settings > Ara API. Keys are capability-scoped:
        run, plugins:read, secrets:read, secrets:write, sessions:read,
        knowledge:read, repos:read, repos:write, reviews:read, reviews:write,
        analytics:read, org:read, org:write, attachments:read,
        attachments:write, plugins:write, guardrails:read, guardrails:write.

````