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

# StackOne Agent

> Build connectors with AI using Claude Code, Cursor, or any MCP-compatible IDE

The **StackOne Agent** is an AI assistant that creates complete StackOne Connector configurations. It can run inside a coding agent (Claude Code preferred, Cursor or others supported) and is also available as a standalone agent (no separate coding agent subscription required when used standalone). It leverages 20+ specialised MCP tools to research APIs, generate and validate YAML, and exhaustively test actions using the Falcon execution engine.

<Note>
  StackOne Agent is in early access. Contact [support@stackone.com](mailto:support@stackone.com) for credentials.
</Note>

***

## What It Does

<CardGroup cols={2}>
  <Card title="Research APIs" icon="magnifying-glass">
    Discovers provider documentation and endpoints automatically
  </Card>

  <Card title="Generate YAML" icon="file-code">
    Creates complete connector configurations following the Falcon spec
  </Card>

  <Card title="Validate & Test" icon="flask">
    Validates syntax and tests actions against real APIs
  </Card>

  <Card title="MCP Testing" icon="comments">
    Conversational testing with automatic tool description improvements
  </Card>
</CardGroup>

***

## Setup

### Step 1: Install Dependencies

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

### Step 2: Fork the Template Repository

```bash theme={null}
git clone https://github.com/YOUR-ORG/connectors-template.git
cd connectors-template
npm install
```

### Step 3: Configure MCP Tools

```bash theme={null}
npx @stackone/cli agent setup --local
```

This configures your IDE with the MCP server connection. The agent credentials are stored securely as environment variables.

### Step 4: Start Building

Open your IDE and prompt:

```
Build a connector for HiBob HRIS with employee management actions.
```

***

## How It Works

The agent follows a strict 8-step workflow:

<Frame>
  <img src="https://mintcdn.com/stackone-60/EwDvhPIppDul_dNC/images/guides/ai-builder-workflow.svg?fit=max&auto=format&n=EwDvhPIppDul_dNC&q=85&s=88b7ec7d8c5cfe8942c8b210b0647732" alt="StackOne Agent workflow: Research → Version Validation → Config Building → YAML Validation → MCP Testing → Description Refinement → Security → Meta Feedback" width="800" height="120" data-path="images/guides/ai-builder-workflow.svg" />
</Frame>

1. **Research** - Discovers API documentation and endpoints
2. **Version Validation** - Resolves API version conflicts
3. **Config Building** - Generates YAML with all actions
4. **YAML Validation** - Runs `stackone validate`
5. **MCP Testing** - Conversational testing via MCP skill
6. **Description Refinement** - Improves tool descriptions based on test results
7. **Security** - Scrambles credentials before storage
8. **Meta Feedback** - Reports results for improvement

***

## MCP Tools

The agent has access to 20+ specialized tools:

### Research Tools

| Tool                   | Description                             |
| ---------------------- | --------------------------------------- |
| `discover_actions`     | Autonomous API discovery (5-15 min)     |
| `get_provider_actions` | Check S3 for indexed actions            |
| `vector_search`        | Semantic search StackOne knowledge base |
| `web_search`           | Web search for API documentation        |
| `fetch`                | Retrieve content from URLs              |

### Analysis Tools

| Tool                        | Description                                  |
| --------------------------- | -------------------------------------------- |
| `analyze_versioning`        | Detect and resolve API version conflicts     |
| `get_external_integrations` | Find how others integrate with the provider  |
| `scan_external_repo`        | Search open-source connector implementations |
| `extract_oas_actions`       | Parse OpenAPI specifications                 |

### Validation Tools

| Tool                   | Description                       |
| ---------------------- | --------------------------------- |
| `test_actions`         | Batch test connector actions      |
| `scramble_credentials` | Secure credentials before storage |

### StackOne Context

| Tool                      | Description                            |
| ------------------------- | -------------------------------------- |
| `get_stackone_categories` | Available categories (hris, ats, crm)  |
| `get_stackone_actions`    | Unified operations for a category      |
| `get_provider_coverage`   | Current StackOne coverage for provider |
| `get_docs`                | StackOne documentation index           |

***

## Agent Instructions

The agent's behavior is defined in `CLAUDE.md` at your repository root. Key sections:

**Workflow:** Strict 11-step process from research to completion

**Naming Conventions:**

* Provider folder: `connectors/provider/` (lowercase)
* Config file: `provider.connector.s1.yaml`

**Quality Standards:**

* Clear descriptions (1-2 sentences) for all operations
* Full CRUD operations where applicable
* Error handling and rate limiting
* Conversational MCP testing for validation

<Card title="CLAUDE.md - Agent Instructions" icon="github" href="https://github.com/StackOneHQ/connectors-template/blob/main/CLAUDE.md">
  View the complete agent instructions and MCP tool documentation on GitHub.
</Card>

***

## Example Session

**You:**

> Create a connector for HiBob HRIS with employee management actions

**Agent:**

> I'll start by researching the HiBob API. Launching action discovery...
>
> \[Uses `discover_actions("hibob")`]
> \[Uses `get_stackone_actions("hris")`]
> \[Uses `vector_search("authentication", "hibob")`]
>
> Based on my research, HiBob uses Basic Auth with a service user ID and token.
> I've identified 15 relevant endpoints. Creating the connector configuration...

The agent creates:

* `connectors/hibob/hibob.connector.s1.yaml` (main file)
* `connectors/hibob/hibob.employees.s1.partial.yaml`
* `connectors/hibob/hibob.time_off.s1.partial.yaml`

Then validates, tests all actions, and reports completion.

***

## MCP Testing Skill

The agent includes a built-in MCP testing skill for conversational validation:

<Card title="MCP Testing Skill" icon="github" href="https://github.com/StackOneHQ/connectors-template/tree/main/.claude/skills/test-mcp-connector">
  View the test-mcp-connector skill that enables conversational testing with automatic tool description improvements.
</Card>

**Key features:**

* **Conversational testing** - Test actions through natural language prompts
* **Tool description refinement** - Automatically improves descriptions based on test results
* **Real API validation** - Tests against actual provider endpoints

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not connecting">
    * Run `stackone agent setup --local` again
    * Verify credentials are correct
    * Restart your IDE after setup
    * Check that `.cursor/mcp.json` or equivalent was created
  </Accordion>

  <Accordion title="Agent not using tools">
    * Verify `CLAUDE.md` is at repository root
    * Check MCP configuration in IDE settings
    * Ensure the file follows the correct format
  </Accordion>

  <Accordion title="Validation errors">
    * Run `stackone validate <file>` manually
    * Check `connectors/README.md` for YAML structure
    * Ensure all required fields are present
  </Accordion>

  <Accordion title="Test failures">
    * Use `--debug` flag to see full request/response
    * Verify credentials are correct and not expired
    * Check action IDs match exactly (case-sensitive)
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Connector Structure" icon="book" href="/guides/connector-engine/connector-structure">
    Complete YAML configuration reference
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>
</CardGroup>