Skip to main content
StackOne’s Connector Engine (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 [email protected] for access.

​
How It Works

Falcon 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 enterprise 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

1

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

Learn from Existing Connectors (Optional)

Download existing connectors to understand the YAML structure:
# Download a connector as reference
stackone get [email protected] --output ./examples/

# View the structure
ls ./examples/bamboohr/
This gives you working examples of authentication patterns, pagination, and action definitions.
3

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

Build Your Connector

5

Validate

stackone validate your-provider/
6

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

Deploy

stackone push your-provider/ --api-key YOUR_API_KEY
Or set up CI/CD for automatic deployment:

CI/CD Setup

​
Key Capabilities

FeatureDescription
Step Functionsrequest, paginated_request, map_fields, typecast, group_data
AuthenticationOAuth2, API Key, Basic Auth, Custom headers
ExpressionsJSONPath, String interpolation, JEXL templates
PaginationCursor, offset, and page-based pagination
Conditional LogicInclude arguments only when conditions are met
Rate LimitingBuilt-in request throttling

​
Next Steps

Feature Reference

All YAML engine capabilities

AI Builder

AI-powered connector generation

CLI Reference

All CLI commands

CI/CD Setup

Automated deployment