> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Connectors

> Create custom connectors and make them available in your StackOne projects

StackOne's **Connector Engine** (aka *Falcon*) powers all 200+ pre-built connectors. You can use the same engine to build your own.

<Info>
  This workflow is optimized for **[Claude Code](https://claude.com/claude-code)**, which excels at tool calling and long-horizon tasks required for connector development. The MCP server and tools also work with other AI coding agents like Cursor, VS Code with Claude, and opencode.
</Info>

<Note>
  Custom connectors require enterprise access. Contact [support@stackone.com](mailto:support@stackone.com) for access.
</Note>

***

## How It Works

StackOne Connectors are YAML configurations that define API interactions. Once deployed, StackOne automatically exposes your connector through **multiple protocols**:

<CardGroup cols={3}>
  <Card title="Actions API" icon="code">
    REST endpoints at `api.stackone.com` for traditional backend integrations
  </Card>

  <Card title="MCP Servers" icon="robot">
    Model Context Protocol for AI agents like Claude Code and Cursor
  </Card>

  <Card title="AI Toolset" icon="wrench">
    TypeScript and Python SDKs optimized for LLM tool calling
  </Card>
</CardGroup>

Write your connector once. It works across all StackOne protocols, whether your users are building traditional apps, AI agents, or both.

***

## When to Build Custom Connectors

<CardGroup cols={2}>
  <Card title="Internal Systems" icon="building">
    Connect proprietary APIs or custom-built tools
  </Card>

  <Card title="Provider-Specific Actions" icon="plus">
    Add actions not covered by standard connectors
  </Card>

  <Card title="Niche Providers" icon="puzzle-piece">
    Support vertical-specific SaaS not in our catalog
  </Card>

  <Card title="Custom Mappings" icon="arrows-rotate">
    Transform data to match your requirements
  </Card>
</CardGroup>

***

## Prerequisites

* StackOne Agent Credentials (Contact [support@stackone.com](mailto:support@stackone.com) to request your agent credentials)
* StackOne CLI (`@stackone/cli`)
* API key with **Connectors** scopes enabled (see [API Keys](/guides/api-keys#configure-api-key-scopes-optional))
  * `connectors:read`: required to download connectors from the registry
  * `connectors:write`: required to push and delete connectors
  * `credentials:read`: required so the `run` command can use the credentials of the specified linked account

***

## Quickstart

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @stackone/cli
    ```

    <Tip>
      **Using Node.js?** Fork the [connectors-template](https://github.com/StackOneHQ/connectors-template/) for a pre-configured project structure with CI/CD workflows.
    </Tip>
  </Step>

  <Step title="Learn from Existing Connectors (Optional)">
    Download existing connectors to understand the YAML structure:

    ```bash theme={null}
    # Download a connector as reference
    stackone get bamboohr@1.0.1 --output ./examples/

    # View the structure
    ls ./examples/bamboohr/
    ```

    This gives you working examples of authentication patterns, pagination, and action definitions.
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    stackone agent setup --global
    ```

    This authenticates via OAuth, stores your access token, and configures MCP tools for AI-assisted development. Use `--local` to scope to the current project only.
  </Step>

  <Step title="Build Your Connector">
    <Tabs>
      <Tab title="AI-Assisted (Recommended)">
        Open your IDE (Cursor or VS Code with Claude) and prompt:

        ```
        Build a connector for [Provider Name] with employee management actions.
        ```

        The AI agent will research the API, generate YAML, validate syntax, and test actions automatically.

        <Card title="StackOne Agent Details" icon="robot" href="/guides/connector-engine/stackone-agent" />
      </Tab>

      <Tab title="Manual">
        Create your connector files:

        ```
        your-provider/
        ├── your-provider.connector.s1.yaml
        ├── your-provider.employees.s1.partial.yaml
        └── your-provider.time_off.s1.partial.yaml
        ```

        **Main connector file:**

        ```yaml theme={null}
        # your-provider.connector.s1.yaml
        StackOne: 1.0.0
        info:
          title: Your Provider
          key: your_provider
          version: 1.0.0
          description: Your Provider connector

        baseUrl: https://api.yourprovider.com/v1

        authentication:
          - custom:
              type: custom
              label: API Key
              authorization:
                type: bearer
                token: $.credentials.apiKey
              configFields:
                - key: apiKey
                  label: API Key
                  type: password
                  required: true
                  secret: true

        actions:
          $ref: your_provider.employees
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    stackone validate your-provider/
    ```
  </Step>

  <Step title="Test">
    Create test files and run an action:

    ```bash theme={null}
    # Create test config
    echo '{"environment": "production", "provider": "your_provider"}' > account.json
    echo '{"apiKey": "your_test_api_key"}' > credentials.json

    # Run action
    stackone run \
      --connector your-provider/your-provider.connector.s1.yaml \
      --account account.json \
      --credentials credentials.json \
      --action-id list_employees \
      --debug
    ```

    <Tip>
      **Faster iteration:** Once your connector is pushed or an account is already linked, skip the credentials file and use `--account-id` instead:

      ```bash theme={null}
      stackone run \
        --connector your-provider/your-provider.connector.s1.yaml \
        --account-id acme-corp-provider \
        --action-id list_employees
      ```

      This uses stored credentials from the linked account, making it easier to iterate on action logic.
    </Tip>
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    stackone push your-provider/ --api-key YOUR_API_KEY
    ```

    Or set up CI/CD for automatic deployment:

    <Card title="CI/CD Setup" icon="github" href="/guides/connector-engine/github-workflow" />
  </Step>
</Steps>

***

## Key Capabilities

| Feature               | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| **Step Functions**    | `request`, `paginated_request`, `map_fields`, `typecast`, `group_data` |
| **Authentication**    | OAuth2, API Key, Basic Auth, Custom headers                            |
| **Expressions**       | JSONPath, String interpolation, JEXL templates                         |
| **Pagination**        | Cursor, offset, and page-based pagination                              |
| **Conditional Logic** | Include arguments only when conditions are met                         |
| **Rate Limiting**     | Built-in request throttling                                            |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Your First Connector" icon="rocket" href="/guides/connector-engine/building-first-connector">
    Step-by-step guide from setup to deployment
  </Card>

  <Card title="Feature Reference" icon="book" href="/guides/connector-engine/connector-structure">
    All YAML engine capabilities
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-powered connector generation
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>
</CardGroup>