> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Create your own connector

Choose an auth type, build the connector payload, and create or manage custom connectors in Scalekit.
Create a custom connector to bring an unsupported API or MCP server into Scalekit's secure access model. This guide walks you through building the connector payload, creating the connector, and managing it over its lifecycle — list, update, and delete — with the management API.

## Prerequisites

You need three credentials from your Scalekit environment:

- `SCALEKIT_ENVIRONMENT_URL` — the base URL of your Scalekit environment
- `SCALEKIT_CLIENT_ID` — your environment's client ID
- `SCALEKIT_CLIENT_SECRET` — your environment's client secret

Find these in the Scalekit Dashboard under **Developers → Settings → API Credentials**.

## Create a connector

Create a connector in the Scalekit Dashboard or with the management API. The dashboard provides a guided form for MCP connectors; the management API gives you scriptable control over every connector type and auth pattern.

### Create an MCP connector in the dashboard

Add an MCP connector through a guided form — no payload required.

1. In the Scalekit Dashboard, switch to **AgentKit**.

2. Select **Connectors**.

3. Select **Create custom connector**.

4. Complete the **Add MCP connector** form:

   - **Display name**: a name for the connector, such as `Example MCP`.
   - **Description**: a short description of what the connector connects to.
   - **Icon URL** (optional): an icon for the connector. Must start with `https://`. For best results, use an 800×800px SVG image, such as `https://cdn.example.com/icon.svg`.
   - **Server URL**: the base URL of the MCP server. Must start with `https://`, such as `https://app.example.com/mcp`.
   - **Metadata** (optional): key-value pairs for the connector. Values must be plain strings; nested objects are not supported.

   For **Auth type**, choose how users authenticate when they connect their account:

   - **OAuth**: users authorize access through the provider's OAuth flow, and Scalekit handles the token exchange.
   - **Bearer token**: users provide a long-lived token issued by the provider.
   - **API key**: users provide an API key issued by the provider.

5. Select **Save**. The connector is ready to use when you create a connection.

### Create a connector with the management API

Build the connector payload using the reference and examples that follow, then create the connector with the management API.

## Understand the connector payload

Supported auth types are `OAUTH`, `BASIC`, `BEARER`, and `API_KEY`. Use `OAUTH` when the upstream API or MCP server requires a user authorization flow and token exchange. Use `BASIC`, `BEARER`, or `API_KEY` when it accepts static credentials or long-lived tokens.

MCP providers use the same four auth types as REST API providers, with `is_mcp: true` set in each `auth_patterns[]` entry. OAuth MCP connectors use a simplified `oauth_config: {"pkce_enabled": true}` — the MCP server handles authorization via Dynamic Client Registration. Non-OAuth MCP connectors omit `oauth_config` entirely.

The connector payload uses these common top-level fields:

- `display_name`: Human-readable name for the custom connector
- `description`: Short description of what the connector connects to
- `auth_patterns`: Authentication options supported by the connector
- `proxy_url`: Base URL the proxy should call for the upstream API (mandatory)
- `proxy_enabled`: Whether the proxy is enabled for the connector (mandatory, should be true)

`proxy_url` can also include templated fields when the upstream API requires account-specific values, for example `https://{{domain}}/api`.

Within `auth_patterns`, the most common fields are:

- `type`: The auth type, such as OAUTH, BASIC, BEARER, or API_KEY
- `display_name`: Label shown for that auth option
- `description`: Short explanation of the auth method
- `fields`: Inputs collected for static auth providers such as BASIC, BEARER, and API_KEY. These usually store values such as `username`, `password`, `token`, `api_key`, `domain`, or `version`.
- `account_fields`: Inputs collected for OAUTH connectors when account-scoped values are needed. This is typically used for values tied to a connected account, such as named path parameters.
- `oauth_config`: OAuth-specific configuration, such as authorize and token endpoints
- `auth_header_key_override`: Custom header name when the upstream does not use `Authorization`. For example, some APIs expect auth in a header such as `X-API-Key` instead of the standard `Authorization` header.
- `auth_field_mutations`: Value transformations applied before the credential is sent. This is useful when the upstream expects a prefix, suffix, or default companion value, such as adding a token prefix or setting a fallback password value for Basic auth.
- `is_mcp`: Set to `true` when the upstream is an MCP server. Tells Scalekit to route the connector through MCP tool calling instead of the HTTP proxy.

Below are example payloads for API and MCP connectors across all supported auth patterns.

> caution: Stateless MCP servers only
>
> Scalekit connects to **stateless MCP servers** only. Stateful MCP servers that require persistent sticky connections or MCP session IDs are not supported.

### API Connector

```json
{
  "display_name": "My Asana",
  "description": "Connect to Asana. Manage tasks, projects, teams, and workflow automation",
  "auth_patterns": [
    {
      "type": "OAUTH",
      "display_name": "OAuth 2.0",
      "description": "Authenticate with Asana using OAuth 2.0 for comprehensive project management",
      "fields": [],
      "oauth_config": {
        "authorize_uri": "https://app.asana.com/-/oauth_authorize",
        "token_uri": "https://app.asana.com/-/oauth_token",
        "user_info_uri": "https://app.asana.com/api/1.0/users/me",
        "available_scopes": [
          {
            "scope": "profile",
            "display_name": "Profile",
            "description": "Access user profile information",
            "required": true
          },
          {
            "scope": "email",
            "display_name": "Email",
            "description": "Access user email address",
            "required": true
          }
        ]
      }
    }
  ],
  "proxy_url": "https://app.asana.com/api",
  "proxy_enabled": true
}
```

### Bearer

```json
{
  "display_name": "My Bearer Token Provider",
  "description": "Connect to an API that accepts a static bearer token",
  "auth_patterns": [
    {
      "type": "BEARER",
      "display_name": "Bearer Token",
      "description": "Authenticate with a static bearer token",
      "fields": [
        {
          "field_name": "token",
          "label": "Bearer Token",
          "input_type": "password",
          "hint": "Your long-lived bearer token",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://api.example.com",
  "proxy_enabled": true
}
```

### Basic

```json
{
  "display_name": "My Freshdesk",
  "description": "Connect to Freshdesk. Manage tickets, contacts, companies, and customer support workflows",
  "auth_patterns": [
    {
      "type": "BASIC",
      "display_name": "Basic Auth",
      "description": "Authenticate with Freshdesk using Basic Auth with username and password for comprehensive helpdesk management",
      "fields": [
        {
          "field_name": "domain",
          "label": "Freshdesk Domain",
          "input_type": "text",
          "hint": "Your Freshdesk domain (e.g., yourcompany.freshdesk.com)",
          "required": true
        },
        {
          "field_name": "username",
          "label": "API Key",
          "input_type": "text",
          "hint": "Your Freshdesk API Key",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://{{domain}}/api",
  "proxy_enabled": true
}
```

### API Key

```json
{
  "display_name": "My Attention",
  "description": "Connect to Attention for AI insights, conversations, teams, and workflows",
  "auth_patterns": [
    {
      "type": "API_KEY",
      "display_name": "API Key",
      "description": "Authenticate with Attention using an API Key",
      "fields": [
        {
          "field_name": "api_key",
          "label": "Integration Token",
          "input_type": "password",
          "hint": "Your Attention API Key",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://api.attention.tech",
  "proxy_enabled": true
}
```

### MCP Connector

```json
{
  "display_name": "Github MCP",
  "description": "Connect to Github MCP",
  "auth_patterns": [
    {
      "description": "Authenticate with Github MCP using browser OAuth.",
      "display_name": "OAuth 2.1/DCR",
      "fields": [],
      "is_mcp": true,
      "oauth_config": {
        "pkce_enabled": true
      },
      "type": "OAUTH"
    }
  ],
  "proxy_url": "https://api.githubcopilot.com/mcp/",
  "proxy_enabled": true
}
```

### Bearer

```json
{
  "display_name": "Apify MCP",
  "description": "Connect to Apify MCP to run web scraping, browser automation, and data extraction Actors directly from your AI workflows.",
  "auth_patterns": [
    {
      "description": "Authenticate with Apify using your API Token.",
      "display_name": "Apify Token",
      "fields": [
        {
          "field_name": "token",
          "hint": "Your Apify API Token",
          "input_type": "password",
          "label": "Apify Token",
          "required": true
        }
      ],
      "is_mcp": true,
      "type": "BEARER"
    }
  ],
  "proxy_url": "https://mcp.apify.com",
  "proxy_enabled": true
}
```

### Basic

```json
{
  "display_name": "My Internal MCP",
  "description": "Connect to an internal MCP server that authenticates with a username and password",
  "auth_patterns": [
    {
      "type": "BASIC",
      "display_name": "Basic Auth",
      "description": "Authenticate with a username and password",
      "is_mcp": true,
      "fields": [
        {
          "field_name": "username",
          "label": "Username",
          "input_type": "text",
          "hint": "Your username",
          "required": true
        },
        {
          "field_name": "password",
          "label": "Password",
          "input_type": "password",
          "hint": "Your password",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://mcp.internal.example.com",
  "proxy_enabled": true
}
```

### API Key

```json
{
  "display_name": "My API Key MCP",
  "description": "Connect to an MCP server that authenticates with a static API key",
  "auth_patterns": [
    {
      "type": "API_KEY",
      "display_name": "API Key",
      "description": "Authenticate with a static API key",
      "is_mcp": true,
      "fields": [
        {
          "field_name": "api_key",
          "label": "API Key",
          "input_type": "password",
          "hint": "Your API key",
          "required": true
        }
      ]
    }
  ],
  "proxy_url": "https://mcp.example.com",
  "proxy_enabled": true
}
```

**Before submitting, review the final payload carefully:**

- `display_name` and `description`
- The selected auth `type`
- Required `fields` and `account_fields`
- OAuth endpoints and scopes, if the connector uses OAuth
- `proxy_url`
- Whether `is_mcp` is set to `true` for MCP providers

## Generate an access token

All API requests require a short-lived access token. Generate one using your `SCALEKIT_CLIENT_ID` and `SCALEKIT_CLIENT_SECRET`:

```bash
curl --location "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$SCALEKIT_CLIENT_ID" \
  --data-urlencode "client_secret=$SCALEKIT_CLIENT_SECRET"
```

Use the `access_token` value from the response as `$env_access_token` in the `curl` commands below.

Use the payload for your auth type as the request body in the create request:

```bash
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers" \
  --header "Authorization: Bearer $env_access_token" \
  --header "Content-Type: application/json" \
  --data '{...}'
```

A successful request returns the created connector. Next, create a connection in the Scalekit Dashboard, then continue with the standard connector flow to authorize users and call tools.

## List connectors

List existing connectors before you create one, to confirm whether a connector for the upstream already exists. You also need the list to find a connector's `identifier` for update and delete requests.

```bash
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/providers?filter.provider_type=CUSTOM&page_size=1000" \
  --header "Authorization: Bearer $env_access_token"
```

## Update a connector

Use the [List connectors](#list-connectors) API to get the connector `identifier`, then send the updated payload:

```bash
curl --location --request PUT "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
  --header "Authorization: Bearer $env_access_token" \
  --header "Content-Type: application/json" \
  --data '{...}'
```

## Delete a connector

Use the [List connectors](#list-connectors) API to get the connector `identifier`. If the connector is still in use, remove the related connections or connected accounts first.

```bash
curl --location --request DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
  --header "Authorization: Bearer $env_access_token"
```

## Next steps

With the connector created and a connection in place, authorize a user and start calling the upstream:

- [Making tool calls](/agentkit/bring-your-own-connector/making-tool-calls) — call the upstream API or MCP server through your connector.


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |