---
title: "Connect a customer-supplied MCP server (static creds or OAuth)"
method: POST
path: "/v1/integrations/connections/custom-mcp"
tags: ["integrations"]
---

# Connect a customer-supplied MCP server (static creds or OAuth)

`POST /v1/integrations/connections/custom-mcp`

Static-cred connections are born ``active``; OAuth returns an
``authorize_url`` + ``state`` and the row starts ``pending_oauth`` until the
``/integrations/oauth/callback`` redirect lands. ``server_url`` (and any
OAuth endpoint URLs) are SSRF-validated in the service layer.

## Request body

- CustomMcpConnectionCreate — Body for ``POST /v1/integrations/connections/custom-mcp``. One shape for all four auth types. ``none``/``bearer``/``api_key`` are the static-credential paths (Step 6 — the row is born ``active``); ``oauth`` is the authorization-code path (Step 7 — the row starts ``pending_oauth`` and the response carries ``authorize_url`` + ``state``). The OAuth endpoint URLs are optional because :func:`discover_mcp_oauth` fills them in when the server advertises RFC 9728 metadata; customer-supplied values override discovery.
  - `nickname` string, required
  - `server_url` string, required
  - `transport` string
  - `auth_type` string
  - `token` string, nullable
  - `api_key` string, nullable
  - `api_key_header` string
  - `headers` object
  - `oauth_authorize_url` string, nullable
  - `oauth_token_url` string, nullable
  - `oauth_client_id` string, nullable
  - `oauth_client_secret` string, nullable
  - `oauth_scopes` string[]

## Response `201`

Successful Response

- CustomMcpConnectResponse — Returned by ``POST /v1/integrations/connections/custom-mcp``. ``authorize_url`` + ``state`` are populated only for the ``oauth`` path so the frontend can redirect the user to the provider; the static paths return ``status="active"`` with both ``None``.
  - `connection_id` string, uuid, required
  - `status` string, required
  - `vendor` string, required
  - `authorize_url` string, nullable
  - `state` string, nullable

## Other responses

- `400` — Bad request
- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/revisions/888bdd5c076e/schema)