AGagentarea
v1
protected
mcp-server-instances

Create Mcp Server Instance

Changed on

Create a new MCP server instance.

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

post/v1/workspaces/{workspace}/mcp-server-instances/

Request

Path parameters

workspacestring required

Slug of the workspace the request acts in

Request body

auth_config_idstring nullable

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

context_secretstring nullable

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.

descriptionstring nullable

Optional human-readable description of the instance.

json_specobject required

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

namestring required

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

server_spec_idstring uuid required

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

Response

Successful Response

costobject nullable
created_atstring date-time required
descriptionstring nullable required
eventsobject nullable
idstring uuid required
is_ownerboolean
json_specobject required
last_dispatchobject nullable
managed_bystring nullable
namestring required
personalboolean
server_spec_idstring required
toolsobject[] nullable
transport'url' | 'docker' | 'command' | 'bundle' required

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

updated_atstring date-time required
verificationobject required

Changes

  • 4662804c264bRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 1d8a3995ec6cRevision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status