Skip to content
Scalekit Docs
Talk to an EngineerDashboard

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.

Check out the examples
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

Section titled “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

Section titled “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.
    • No authentication: the server is public and requires no credentials. Use this only when the server intentionally allows unauthenticated access and exposes no user-specific data or privileged operations, since every user shares the same anonymous access.

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

Create a connector with the management API

Section titled “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. MCP connectors can also use NO_AUTH for public servers that require no credentials - set is_mcp: true, use an empty fields: [], and omit oauth_config. Use NO_AUTH only when the upstream intentionally allows unauthenticated public access and exposes no user-specific data or privileged operations; every user of the connector shares the same anonymous access.

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.

{
  "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
}

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:

Terminal window
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:

Terminal
# $env_access_token and $SCALEKIT_CLIENT_SECRET are secrets - keep them server-side and out of source control.
# --fail-with-body makes curl exit non-zero and print the error body on a non-2xx response.
curl --fail-with-body --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

Section titled “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.

Terminal
# $env_access_token is a secret - keep it server-side and out of source control.
curl --fail-with-body --location "$SCALEKIT_ENVIRONMENT_URL/api/v1/providers?filter.provider_type=CUSTOM&page_size=1000" \
  --header "Authorization: Bearer $env_access_token"

Update a connector

Section titled “Update a connector”

Use the List connectors API to get the connector identifier, then send the updated payload. Include display_name, proxy_url, and auth_patterns on every update, and echo back any other fields you want to keep - omitted fields are not preserved, so read the current connector first and change only what you need.

Terminal
# $env_access_token and $SCALEKIT_CLIENT_SECRET are secrets - keep them server-side and out of source control.
curl --fail-with-body --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

Section titled “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.

Terminal
# $env_access_token is a secret - keep it server-side and out of source control.
curl --fail-with-body --location --request DELETE "$SCALEKIT_ENVIRONMENT_URL/api/v1/custom-providers/$PROVIDER_IDENTIFIER" \
  --header "Authorization: Bearer $env_access_token"

Next steps

Section titled “Next steps”

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