---
title: "Create a connection (token or mcp)"
method: POST
path: "/connections"
---

# Create a connection (token or mcp)

`POST /connections`

## Request

- Base URL: `https://worker.openhelm.ai/v1`
- URL: `https://worker.openhelm.ai/v1/connections`
- Auth: HTTP bearer

Provision a connection programmatically. `type: "token"` stores an API key/secret in encrypted storage; `type: "mcp"` registers a remote HTTP/SSE MCP server by URL with optional headers (values may use ${SECRET}). For OAuth/browser providers that need a human, use POST /connections/links instead. The `secret` is write-only.

## Request body

- object
  - `name` string, required
  - `type` 'token' | 'mcp', required
  - `secret` string: API key/token to store (token type, or to back ${SECRET} in mcp headers).
  - `env_var_name` string: token type: the env var the secret is injected as (e.g. GITHUB_TOKEN).
  - `url` string, uri: mcp type: the remote MCP server URL.
  - `transport` 'http' | 'sse'
  - `headers` object: mcp type: request headers.
  - `project_id` string: Scope to one project; omit for all the account's runs.
  - `service_id` string: Which service this credential is for, as a catalogue id ("stripe", "contextely", "notion"). Service-aware features match on this and never on the connection's name, so a credential provisioned without it is stored correctly and ignored by all of them. Rejected if unknown.

## Response `201`

Created

## Other responses

- `400`: Invalid type/body, or an unknown service_id

---

[API](https://skmtc.dev/openhelm/apis/openhelm-public-api.md) · [All operations](https://skmtc.dev/openhelm/apis/openhelm-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openhelm/apis/openhelm-public-api/revisions/2af88dc2f6a7?raw)