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 and its agent, then pushes it to your project. To adapt a connector that already exists instead, see Customizing Connectors.

Custom connectors require Enterprise access. Contact [e-mail] to enable.

Before you start

The CLI needs Node.js 22.22 or later. Nothing else is required.

Installing Node.js

macOS

• Open Terminal (press Cmd + Space, type Terminal, press Enter).
• Check what you have: node --version.
• No Node.js 22.22+? Install it from nodejs.org.

Windows

• Open Command Prompt or PowerShell from the Start menu.
• Check what you have: node --version.
• No Node.js 22.22+? Install it from nodejs.org.

Linux

• Open your terminal application.
• Check what you have: node --version.
• Install Node.js 22.22+ from nodejs.org or NodeSource, since distribution packages are often older.

1. Generate an API key

   Create an API key with the connectors:read, connectors:write, and credentials:read scopes.

2. Install the CLI

   Install the StackOne CLI globally via npm:

   npm install -g @stackone/cli
   

   The -g flag installs the CLI globally so the stackone command is available in any directory.

   Verify the install. It prints the installed version:

   stackone --version
   
3. Set up your workspace

   Make a directory to hold your connectors and move into it:

   mkdir custom-connectors && cd custom-connectors
   
4. Configure the CLI

   From inside your working directory, set up the agent:

   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, slash commands, and subagents into .claude/ along with a guide block in CLAUDE.md.

   The CLI owns everything under .claude/, so re-run stackone agent sync after each CLI update to pick up new skills and commands.

5. Create a CLI profile

   Create a named profile so deployment commands like stackone push can authenticate without you pasting your API key each time:

   stackone init
   

   You’ll be prompted for a profile label and an API key. Paste the key you generated above. Profiles point at production unless you pass --env staging, so create one of each if you deploy to both, then reference them with --profile [profile-label].

6. Build it

   Open Claude Code in your working directory:

   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 command that agent setup --local installed, which walks you through the build rather than leaving you to describe it:

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

   This command needs CLI 1.47.0 or later. Earlier versions install the other connector skills but skip this one, so if it isn’t listed, update the CLI and re-run stackone agent sync.

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

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

   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.
   
7. Validate and test

   The agent reports the directory it wrote the connector to. Substitute that path for [connector-dir] below.

   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:

   stackone validate [connector-dir] --watch
   

   run executes a single action for real against the provider, so you see what it returns rather than what the YAML claims. Before you push, point it at local account and credential files:

   echo '{"environment": "production", "provider": "[provider]"}' > account.json
   echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json
   

   Add credentials.json to .gitignore so credentials never reach version control.

   --debug adds the raw request and response and each step’s inputs and outputs:

   stackone run --connector [connector-dir]/[provider].connector.s1.yaml \
     --account account.json --credentials credentials.json \
     --action-id [action-id] --debug
   

   Once the connector is pushed and an account is linked, swap both files for --account-id [account-id] --profile [profile-label]. That path needs a profile, because the CLI fetches the stored credentials from the API.

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

   Debugging

   What --debug surfaces, and the common symptoms with their causes.

9. 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:

   stackone push [connector-dir] --profile [profile-label]
   

   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 builds on.

Build Workflow

Covers authentication patterns, testing against an account, and the iterate loop.

Connector YAML Reference

Every field, step function, and expression the schema supports.

Customizing Connectors

Pull an existing connector, change it, and push it back.

Connector Versioning

Release new versions without breaking existing linked accounts.