Skip to main content
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 support@stackone.com to enable.

​
Before you start

The CLI needs Node.js 18+. Nothing else is required.
  • Open Terminal — press Cmd + Space, type Terminal, press Enter.
  • Check what you have: node --version.
  • No Node.js 18+? Install it from nodejs.org.
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:
The -g flag installs the CLI globally so the stackone command is available in any directory.
Verify the install. It prints the installed version:
3

Set up your workspace

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

Configure the CLI

From inside your working directory, set up the agent:
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.
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:
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].
6

Build it

Open Claude Code in your working directory:
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:
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:
7

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

Each stage in detail — 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.