> ## 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.

# First Connector

> Build, test, and deploy your first StackOne connector.

A connector turns a third-party API into agent-ready actions, defined as YAML. This guide builds one from scratch with the [StackOne CLI](/connector-building/stackone-cli) and its agent, then pushes it to your project. To adapt a connector that already exists instead, see [Customizing Connectors](/connector-building/customizing-connectors).

<Warning>
  Custom connectors require Enterprise access — contact [support@stackone.com](mailto:support@stackone.com) to enable.
</Warning>

## Before you start

The CLI needs **Node.js 18+**. Nothing else is required.

<Accordion title="Installing Node.js">
  <Tabs>
    <Tab title="macOS">
      * Open **Terminal** — press `Cmd + Space`, type Terminal, press Enter.
      * Check what you have: `node --version`.
      * No Node.js 18+? Install it from [nodejs.org](https://nodejs.org/).
    </Tab>

    <Tab title="Windows">
      * Open **Command Prompt** or **PowerShell** from the Start menu.
      * Check what you have: `node --version`.
      * No Node.js 18+? Install it from [nodejs.org](https://nodejs.org/).
    </Tab>

    <Tab title="Linux">
      * Open your terminal application.
      * Check what you have: `node --version`.
      * Install it with your package manager — for example `sudo apt install nodejs` on Debian or Ubuntu, `sudo dnf install nodejs` on Fedora.
    </Tab>
  </Tabs>
</Accordion>

<Steps>
  <Step title="Generate an API key">
    Create an [API key](/embed/api-keys) with the `connectors:read`, `connectors:write`, and `credentials:read` scopes.
  </Step>

  <Step title="Install the CLI">
    Install the StackOne CLI globally via npm:

    ```bash theme={null}
    npm install -g @stackone/cli
    ```

    <Note>
      The `-g` flag installs the CLI globally so the `stackone` command is available in any directory.
    </Note>

    Verify the install. It prints the installed version:

    ```bash theme={null}
    stackone --version
    ```
  </Step>

  <Step title="Set up your workspace">
    Make a directory to hold your connectors and move into it:

    ```bash theme={null}
    mkdir custom-connectors && cd custom-connectors
    ```
  </Step>

  <Step title="Configure the CLI">
    From inside your working directory, set up the agent:

    ```bash theme={null}
    stackone agent setup --local
    ```

    This authenticates you, writes an `.mcp.json` so your AI assistant gets StackOne's tools, and installs the connector-building skills into `.claude/skills/` along with a guide block in `CLAUDE.md`.
  </Step>

  <Step title="Create a CLI profile">
    Create a named profile so deployment commands like `stackone push` can authenticate without you pasting your API key each time:

    ```bash theme={null}
    stackone init
    ```

    You'll be prompted for a profile label and an API key. Paste the key you generated above. Create separate profiles for staging and production, then reference them with `--profile [profile-label]`.
  </Step>

  <Step title="Build it">
    Open [Claude Code](https://claude.com/claude-code) in your working directory:

    ```bash theme={null}
    claude
    ```

    It picks up the `.mcp.json` and the skills that `agent setup --local` just installed. Approve the StackOne MCP server when prompted, so the agent can reach StackOne's tools.

    Then run the onboarding skill, which walks you through the build rather than leaving you to describe it:

    ```text theme={null}
    /connector-onboarding
    ```

    It asks which provider you're connecting to and what kind of connector you want, then works through authentication, the endpoints worth exposing, and the actions themselves, confirming each part with you before moving on.

    Have the provider's API documentation to hand, along with the authentication type you plan to use.

    You can also skip the skill and describe what you want in plain language, letting the agent work out the endpoints, pagination, and field mappings from the provider's documentation:

    ```text theme={null}
    I want to connect to Acme HR, our HR system. Their API docs are at
    https://developer.acme.com/reference and we authenticate with an API key.
    I want to be able to look up who works at the company, along with their
    job title and manager.
    ```
  </Step>

  <Step title="Validate and test">
    `validate` checks the YAML against the connector schema and reports what's malformed or missing. `--watch` keeps it running so it rechecks every time you save:

    ```bash theme={null}
    stackone validate connectors/[provider]/ --watch
    ```

    `run` executes a single action for real against a linked account, so you see what the provider returns rather than what the YAML claims. `--debug` adds the raw request and response and each step's inputs and outputs:

    ```bash theme={null}
    stackone run --connector connectors/[provider]/[provider].connector.s1.yaml \
      --account-id [account-id] --action-id [action-id] --debug
    ```
  </Step>

  <Step title="Refine">
    Expect to go back and forth between building and testing. Tell the agent what you saw and rerun the action until it returns what you want.

    <Card title="Debugging" icon="bug" href="/connector-building/build-workflow#debugging">
      What `--debug` surfaces, and the common symptoms with their causes.
    </Card>
  </Step>

  <Step title="Push it">
    `push` uploads the connector to your project's registry, which is what makes it available to link accounts against. `--profile` is the name you set with `stackone init`:

    ```bash theme={null}
    stackone push connectors/[provider]/ --profile [profile-label]
    ```

    <Tip>
      Connectors are code, so keeping them in version control gives you history and review as they change. It's also what publishing through [GitHub CI/CD](/connector-building/github-ci-cd) builds on.
    </Tip>
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Build Workflow" icon="diagram-project" href="/connector-building/build-workflow">
    Each stage in detail — authentication patterns, testing against an account, and the iterate loop.
  </Card>

  <Card title="Connector YAML Reference" icon="file-code" href="/connector-yaml-reference/overview">
    Every field, step function, and expression the schema supports.
  </Card>

  <Card title="Customizing Connectors" icon="sliders" href="/connector-building/customizing-connectors">
    Pull an existing connector, change it, and push it back.
  </Card>

  <Card title="Connector Versioning" icon="code-branch" href="/connector-building/connector-versioning">
    Release new versions without breaking existing linked accounts.
  </Card>
</CardGroup>