Build Connectors

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

This workflow is optimized for 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.

Custom connectors require enterprise access. Contact support@stackone.com for access.

How It Works

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

Actions API

REST endpoints at api.stackone.com for traditional backend integrations

MCP Servers

Model Context Protocol for AI agents like Claude Code and Cursor

AI Toolset

TypeScript and Python SDKs optimized for LLM tool calling

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

Internal Systems

Connect proprietary APIs or custom-built tools

Provider-Specific Actions

Add actions not covered by standard connectors

Niche Providers

Support vertical-specific SaaS not in our catalog

Custom Mappings

Transform data to match your requirements

Prerequisites

StackOne Agent Credentials (Contact support@stackone.com to request your agent credentials)
StackOne CLI (@stackone/cli)
API key with Connectors scopes enabled (see API Keys)
- 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

Install the CLI

npm install -g @stackone/cli

Using Node.js? Fork the connectors-template for a pre-configured project structure with CI/CD workflows.

Learn from Existing Connectors (Optional)

Download existing connectors to understand the YAML structure:

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

Authenticate

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.

Build Your Connector

AI-Assisted (Recommended)
Manual

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.

StackOne Agent Details

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:

# 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

Validate

stackone validate your-provider/

Test

Create test files and run an action:

# 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

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

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.

Deploy

stackone push your-provider/ --api-key YOUR_API_KEY

Or set up CI/CD for automatic deployment:

CI/CD Setup

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

Build Your First Connector

Step-by-step guide from setup to deployment

Feature Reference

All YAML engine capabilities

StackOne Agent

AI-powered connector generation

CLI Reference

All CLI commands

Quickstart

Connect Tools

Dashboard

Build Connectors

How It Works

Actions API

MCP Servers

AI Toolset

When to Build Custom Connectors

Internal Systems

Provider-Specific Actions

Niche Providers

Custom Mappings

Prerequisites

Quickstart

StackOne Agent Details

CI/CD Setup

Key Capabilities

Next Steps

Build Your First Connector

Feature Reference

StackOne Agent

CLI Reference

​How It Works

Actions API

MCP Servers

AI Toolset

​When to Build Custom Connectors

Internal Systems

Provider-Specific Actions

Niche Providers

Custom Mappings

​Prerequisites

​Quickstart

StackOne Agent Details

CI/CD Setup

​Key Capabilities

​Next Steps

Build Your First Connector

Feature Reference

StackOne Agent

CLI Reference

How It Works

When to Build Custom Connectors

Prerequisites

Quickstart

Key Capabilities

Next Steps