> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentarea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Mcp Server Connection

> Create an MCP server spec and instance in one transaction.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/mcp-server-instances/with-spec
openapi: 3.1.0
info:
  description: >-
    Modular and extensible framework for building AI agents. This API requires
    JWT Bearer token authentication for most endpoints. Include your JWT token
    in the Authorization header. Public endpoints include /, /health, /docs,
    /redoc, and /openapi.json.
  title: AgentArea API
  version: 0.1.0
servers: []
security:
  - bearer: []
paths:
  /v1/mcp-server-instances/with-spec:
    post:
      tags:
        - v1
        - protected
        - mcp-server-instances
      summary: Create Mcp Server Connection
      description: Create an MCP server spec and instance in one transaction.
      operationId: create_mcp_server_connection_v1_mcp_server_instances_with_spec_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPServerConnectionCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServerInstanceResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - HTTPBearer: []
components:
  schemas:
    MCPServerConnectionCreateRequest:
      properties:
        instance:
          $ref: '#/components/schemas/MCPServerInstanceCreateWithoutSpec'
        server:
          $ref: '#/components/schemas/MCPServerCreate'
      required:
        - server
        - instance
      title: MCPServerConnectionCreateRequest
      type: object
    MCPServerInstanceResponse:
      properties:
        auth_config_id:
          anyOf:
            - format: uuid
              type: string
            - type: string
            - type: 'null'
          title: Auth Config Id
        created_at:
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        id:
          format: uuid
          title: Id
          type: string
        json_spec:
          additionalProperties: true
          title: Json Spec
          type: object
        last_dispatch:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Last Dispatch
        name:
          title: Name
          type: string
        server_spec_id:
          title: Server Spec Id
          type: string
        tools:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools
        updated_at:
          title: Updated At
          type: string
        verification:
          additionalProperties: true
          title: Verification
          type: object
      required:
        - id
        - name
        - description
        - server_spec_id
        - json_spec
        - verification
        - created_at
        - updated_at
      title: MCPServerInstanceResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    MCPServerInstanceCreateWithoutSpec:
      properties:
        auth_config_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Auth Config Id
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        json_spec:
          additionalProperties: true
          title: Json Spec
          type: object
        name:
          title: Name
          type: string
      required:
        - name
      title: MCPServerInstanceCreateWithoutSpec
      type: object
    MCPServerCreate:
      additionalProperties: false
      description: |-
        Payload for creating an MCP server spec (catalog template).

        Either ``docker_image_url`` (for container-based servers) or
        ``remote_url`` (for HTTP-based servers like GitHub Copilot) should be
        supplied. ``env_schema`` describes the variables an instance built from
        this spec needs to provide; secret entries (``isSecret: true``) are
        routed through the secret manager rather than stored in plaintext.
      properties:
        cmd:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Custom command override for container CMD (e.g. switching between
            stdio and HTTP modes).
          title: Cmd
        description:
          description: Short summary of what this MCP server provides.
          title: Description
          type: string
        docker_image_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Docker image URL for container-based MCP servers.
          title: Docker Image Url
        env_schema:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: >-
            Environment-variable schema entries (KeyValueInput from the MCP
            registry). Each item has at least 'name' and 'description'; mark
            secrets with 'isSecret: true'.
          title: Env Schema
        is_public:
          default: false
          description: If true, the spec is visible across workspaces.
          title: Is Public
          type: boolean
        json_spec:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Raw ServerJSON spec as published by the MCP registry.
          title: Json Spec
        name:
          description: Human-readable MCP server name (unique per workspace).
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        registry_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Source registry URL the spec was imported from.
          title: Registry Url
        remote_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Remote endpoint URL for HTTP-based MCP servers.
          title: Remote Url
        tags:
          description: Tags used for search and categorization.
          items:
            type: string
          title: Tags
          type: array
        version:
          default: 1.0.0
          description: Semantic version of the MCP server spec.
          title: Version
          type: string
      required:
        - name
        - description
      title: MCPServerCreate
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: JWT Bearer token for authentication
      scheme: bearer
      type: http
    HTTPBearer:
      scheme: bearer
      type: http

````