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.

In the Scalekit Dashboard, switch to AgentKit.
Select Connectors.
Select Create custom connector.
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.
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.

API Connector
MCP Connector

1
{
2
  "display_name": "My Asana",
3
  "description": "Connect to Asana. Manage tasks, projects, teams, and workflow automation",
4
  "auth_patterns": [
5
    {
6
      "type": "OAUTH",
7
      "display_name": "OAuth 2.0",
8
      "description": "Authenticate with Asana using OAuth 2.0 for comprehensive project management",
9
      "fields": [],
10
      "oauth_config": {
11
        "authorize_uri": "https://app.asana.com/-/oauth_authorize",
12
        "token_uri": "https://app.asana.com/-/oauth_token",
13
        "user_info_uri": "https://app.asana.com/api/1.0/users/me",
14
        "available_scopes": [
15
          {
16
            "scope": "profile",
17
            "display_name": "Profile",
18
            "description": "Access user profile information",
19
            "required": true
20
          },
21
          {
22
            "scope": "email",
23
            "display_name": "Email",
24
            "description": "Access user email address",
25
            "required": true
26
          }
27
        ]
28
      }
29
    }
30
  ],
31
  "proxy_url": "https://app.asana.com/api",
32
  "proxy_enabled": true
33
}

1
{
2
  "display_name": "My Bearer Token Provider",
3
  "description": "Connect to an API that accepts a static bearer token",
4
  "auth_patterns": [
5
    {
6
      "type": "BEARER",
7
      "display_name": "Bearer Token",
8
      "description": "Authenticate with a static bearer token",
9
      "fields": [
10
        {
11
          "field_name": "token",
12
          "label": "Bearer Token",
13
          "input_type": "password",
14
          "hint": "Your long-lived bearer token",
15
          "required": true
16
        }
17
      ]
18
    }
19
  ],
20
  "proxy_url": "https://api.example.com",
21
  "proxy_enabled": true
22
}

1
{
2
  "display_name": "My Freshdesk",
3
  "description": "Connect to Freshdesk. Manage tickets, contacts, companies, and customer support workflows",
4
  "auth_patterns": [
5
    {
6
      "type": "BASIC",
7
      "display_name": "Basic Auth",
8
      "description": "Authenticate with Freshdesk using Basic Auth with username and password for comprehensive helpdesk management",
9
      "fields": [
10
        {
11
          "field_name": "domain",
12
          "label": "Freshdesk Domain",
13
          "input_type": "text",
14
          "hint": "Your Freshdesk domain (e.g., yourcompany.freshdesk.com)",
15
          "required": true
16
        },
17
        {
18
          "field_name": "username",
19
          "label": "API Key",
20
          "input_type": "text",
21
          "hint": "Your Freshdesk API Key",
22
          "required": true
23
        }
24
      ]
25
    }
26
  ],
27
  "proxy_url": "https://{{domain}}/api",
28
  "proxy_enabled": true
29
}

1
{
2
  "display_name": "My Attention",
3
  "description": "Connect to Attention for AI insights, conversations, teams, and workflows",
4
  "auth_patterns": [
5
    {
6
      "type": "API_KEY",
7
      "display_name": "API Key",
8
      "description": "Authenticate with Attention using an API Key",
9
      "fields": [
10
        {
11
          "field_name": "api_key",
12
          "label": "Integration Token",
13
          "input_type": "password",
14
          "hint": "Your Attention API Key",
15
          "required": true
16
        }
17
      ]
18
    }
19
  ],
20
  "proxy_url": "https://api.attention.tech",
21
  "proxy_enabled": true
22
}

1
{
2
  "display_name": "Github MCP",
3
  "description": "Connect to Github MCP",
4
  "auth_patterns": [
5
    {
6
      "description": "Authenticate with Github MCP using browser OAuth.",
7
      "display_name": "OAuth 2.1/DCR",
8
      "fields": [],
9
      "is_mcp": true,
10
      "oauth_config": {
11
        "pkce_enabled": true
12
      },
13
      "type": "OAUTH"
14
    }
15
  ],
16
  "proxy_url": "https://api.githubcopilot.com/mcp/",
17
  "proxy_enabled": true
18
}

1
{
2
  "display_name": "Apify MCP",
3
  "description": "Connect to Apify MCP to run web scraping, browser automation, and data extraction Actors directly from your AI workflows.",
4
  "auth_patterns": [
5
    {
6
      "description": "Authenticate with Apify using your API Token.",
7
      "display_name": "Apify Token",
8
      "fields": [
9
        {
10
          "field_name": "token",
11
          "hint": "Your Apify API Token",
12
          "input_type": "password",
13
          "label": "Apify Token",
14
          "required": true
15
        }
16
      ],
17
      "is_mcp": true,
18
      "type": "BEARER"
19
    }
20
  ],
21
  "proxy_url": "https://mcp.apify.com",
22
  "proxy_enabled": true
23
}

1
{
2
  "display_name": "My Internal MCP",
3
  "description": "Connect to an internal MCP server that authenticates with a username and password",
4
  "auth_patterns": [
5
    {
6
      "type": "BASIC",
7
      "display_name": "Basic Auth",
8
      "description": "Authenticate with a username and password",
9
      "is_mcp": true,
10
      "fields": [
11
        {
12
          "field_name": "username",
13
          "label": "Username",
14
          "input_type": "text",
15
          "hint": "Your username",
16
          "required": true
17
        },
18
        {
19
          "field_name": "password",
20
          "label": "Password",
21
          "input_type": "password",
22
          "hint": "Your password",
23
          "required": true
24
        }
25
      ]
26
    }
27
  ],
28
  "proxy_url": "https://mcp.internal.example.com",
29
  "proxy_enabled": true
30
}

1
{
2
  "display_name": "My API Key MCP",
3
  "description": "Connect to an MCP server that authenticates with a static API key",
4
  "auth_patterns": [
5
    {
6
      "type": "API_KEY",
7
      "display_name": "API Key",
8
      "description": "Authenticate with a static API key",
9
      "is_mcp": true,
10
      "fields": [
11
        {
12
          "field_name": "api_key",
13
          "label": "API Key",
14
          "input_type": "password",
15
          "hint": "Your API key",
16
          "required": true
17
        }
18
      ]
19
    }
20
  ],
21
  "proxy_url": "https://mcp.example.com",
22
  "proxy_enabled": true
23
}

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:

1
curl --location "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
2
  --header 'Content-Type: application/x-www-form-urlencoded' \
3
  --data-urlencode 'grant_type=client_credentials' \
4
  --data-urlencode "client_id=$SCALEKIT_CLIENT_ID" \
5
  --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:

1
curl --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers" \
2
  --header "Authorization: Bearer $env_access_token" \
3
  --header "Content-Type: application/json" \
4
  --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.

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

Update a connector

Use the List connectors API to get the connector identifier, then send the updated payload:

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

Delete a connector

Use the List connectors API to get the connector identifier. If the connector is still in use, remove the related connections or connected accounts first.

1
curl --location --request DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
2
  --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 — call the upstream API or MCP server through your connector.