# Create connection

Create connection metadata and credential references that the agent can reference.

```text
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/connections
```

## Before you call this API

Configure the [regional API endpoint and authentication](https://omnifabric.cloudsigma.com/docs/developer/endpoints-and-authentication.html.md), and select the target workspace.

The example below uses `$CLOUDSIGMA_API_KEY` and `$WORKSPACE_ID`.

## Request example

```bash
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/connections" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MCP 服务",
    "kind": "mcp_server",
    "endpoint_uri": "https://mcp.example.com"
  }'
```

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Connection name. |
| `endpoint_uri` | string | Yes | Connection service address. |
| `description` | string | No | Connection instructions. |
| `status` | string | No | Connection status. |
| `kind` | string | No | Connection type. |
| `auth_type` | string | No | Authentication type. |
| `credential_ref` | string | No | A reference to a saved credential. |
| `capabilities` | string[] | No | List of connection capabilities. |
| `owner_user_id` | string | No | Connection owner user ID. |
| `visibility` | string | No | Visible range. |
| `config` | object | No | Connection configuration. |
| `labels` | object | no | Label. |
| `annotations` | object | No | Comment. |
| `metadata` | object | No | Extended metadata. |
| `credential` | object | No | Credentials, which can contain `bearer_token`, `api_key`, `basic_username`, `basic_password`, or `custom_headers`. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Successful response

Returns `201` and a new connection on success.

```json
{"code":0,"data":{"id":"connection_01","name":"MCP 服务"}}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | New connection ID. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Error response

```json
{"code":2,"message":"invalid connection metadata"}
```