Skip to main content
POST
Create Mcp Server Instance

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspace
string
required

Slug of the workspace the request acts in

Maximum string length: 120
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Body

application/json

Payload for creating an MCP server instance.

The instance's transport (url, docker or command) is the one its server spec declares; the response carries it as transport. json_spec carries the instance's own configuration, e.g. {"environment": {...}, "env_vars": [...]} or {"headers": {...}}; transport keys in it are ignored. For URL-type instances the service synchronously verifies the endpoint; docker/command kick off background verification.

json_spec
Json Spec · object
required

Instance configuration (environment, env_vars, headers). Transport keys such as 'type' are ignored: the server spec declares the transport.

name
string
required

Display name for this MCP server instance (unique per workspace).

Required string length: 1 - 255
server_spec_id
string<uuid>
required

ID of an existing MCP server spec to derive defaults from (env_schema, secret routing, etc.).

auth_config_id
string | null

ID of an MCP auth config (OAuth/credentials) to attach.

context_secret
string | null

URL instances only. Shared secret (at least 32 characters) AgentArea signs each tool call's context token with, so the server can trust which task, workspace and end user the call is for. Write-only: stored in the secret manager; the instance's json_spec shows context_signing: true instead.

Required string length: 32 - 512
description
string | null

Optional human-readable description of the instance.

Response

Successful Response

created_at
string<date-time>
required
description
string | null
required
id
string<uuid>
required
json_spec
Json Spec · object
required
name
string
required
server_spec_id
string
required
transport
enum<string>
required

How a connection is reached: the instance's transport column, set once at creation.

Available options:
url,
docker,
command,
bundle
updated_at
string<date-time>
required
verification
Verification · object
required
auth_config_id
cost
Cost · object | null
events
Events · object | null
last_dispatch
Last Dispatch · object | null
managed_by
string | null
tools
Tools · object[] | null