---
orphan: true
---

# Create connection

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

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/connections
```

## Before you call

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

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/connections" \
  -H "X-API-Key: $AI_STUDIO_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"}
```