---
title: "Create Mcp Server Instance"
method: POST
path: "/v1/mcp-server-instances/"
tags: ["v1", "protected", "mcp-server-instances"]
---

# Create Mcp Server Instance

`POST /v1/mcp-server-instances/`

Create a new MCP server instance.

Returns 201 for url (synchronous verification completed).
Returns 202 for docker/command (background verification in progress).

## Request body

- MCPServerInstanceCreate — Payload for creating an MCP server instance. ``json_spec`` carries the connection configuration. Common shapes: - ``{"type": "url", "endpoint_url": "https://..."}`` - ``{"type": "docker", "environment": {...}, "env_vars": [...]}`` - ``{"type": "command", "command": [...], "environment": {...}}`` For URL-type instances the service synchronously verifies the endpoint; docker/command kick off background verification.
  - `auth_config_id` string, nullable — ID of an MCP auth config (OAuth/credentials) to attach.
  - `description` string, nullable — Optional human-readable description of the instance.
  - `json_spec` object, required — Connection configuration. Must include 'type' ('url' | 'docker' | 'command'); other keys depend on type.
  - `name` string, required — Display name for this MCP server instance (unique per workspace).
  - `server_spec_id` string, required — ID of an existing MCP server spec to derive defaults from (env_schema, secret routing, etc.).

## Response `201`

Successful Response

- MCPServerInstanceResponse
  - `auth_config_id` union
    - string, uuid
    - string
  - `created_at` string, required
  - `description` string, nullable, required
  - `id` string, uuid, required
  - `json_spec` object, required
  - `last_dispatch` object, nullable
  - `name` string, required
  - `server_spec_id` string, required
  - `tools` object[], nullable
  - `updated_at` string, required
  - `verification` object, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.net/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentarea/agentarea-api/versions/e3650e48373b/schema)