# Using AI Coding Agents

### 1. What this setup gives you

The setup combines two layers:

* **Agent skills** give the coding agent procedural knowledge about how to write Hexabot actions and workflows.
* **Hexabot MCP** gives the coding agent live access to Hexabot through:

```txt
http://localhost:3000/api/mcp
```

Vercel Skills are reusable instruction packages for coding agents, and the `npx skills` CLI supports installing skills for several agents, including Claude Code, Codex, OpenCode, Cursor, and many others. ([GitHub](https://github.com/vercel-labs/skills))

### 2. Prerequisites

You need:

* Node.js + npx
* Hexabot API running locally
* A Hexabot account with access to the profile page
* At least one AI coding agent installed

Start Hexabot normally, then open:

```txt
http://localhost:3000/profile
```

Generate an MCP token from your profile page.

<figure><img src="/files/p5G4L53YtOCqgzyuv7Kl" alt=""><figcaption></figcaption></figure>

Store it as an environment variable instead of hardcoding it in config files:

```bash
export HEXABOT_MCP_URL="http://localhost:3000/api/mcp"
export HEXABOT_MCP_TOKEN="paste-your-token-here"
```

For Windows PowerShell:

```powershell
setx HEXABOT_MCP_URL "http://localhost:3000/api/mcp"
setx HEXABOT_MCP_TOKEN "paste-your-token-here"
```

### 3. Install the Hexabot skills

Install the two Hexabot skills:

```bash
npx skills add hexabot-ai/action-creator
npx skills add hexabot-ai/workflow-writer
```

Verify the installation:

```bash
npx skills list
```

## 4. Configure MCP by AI coding tool

### 4.1 Claude Code

Claude Code supports MCP servers over HTTP and lets you configure them globally, per user, or per project. Project-scoped MCP servers are stored in a `.mcp.json` file, and Claude Code supports environment variable expansion in `url` and `headers`, which is useful for keeping tokens out of the repository. ([Claude](https://code.claude.com/docs/en/mcp))

#### Recommended project configuration

Create a file at the root of your Hexabot workspace:

```txt
.mcp.json
```

Add:

```json
{
  "mcpServers": {
    "hexabot": {
      "type": "http",
      "url": "${HEXABOT_MCP_URL:-http://localhost:3000/api/mcp}",
      "headers": {
        "Authorization": "Bearer ${HEXABOT_MCP_TOKEN}"
      }
    }
  }
}
```

Then run:

```bash
claude
```

Inside Claude Code:

```txt
/mcp
```

Use `/mcp` to verify that the `hexabot` server is connected. Claude Code also supports adding HTTP MCP servers from the CLI with `claude mcp add --transport http`. ([Claude](https://code.claude.com/docs/en/mcp))

#### Alternative CLI setup

```bash
claude mcp add --transport http --scope user hexabot http://localhost:3000/api/mcp \
  --header "Authorization: Bearer $HEXABOT_MCP_TOKEN"
```

***

### 4.2 OpenAI Codex CLI

Codex stores user-level configuration in:

```txt
~/.codex/config.toml
```

You can also add project-specific configuration in:

```txt
.codex/config.toml
```

Codex supports MCP server configuration in TOML, including HTTP MCP server URLs and bearer tokens loaded from environment variables. ([OpenAI Developers](https://developers.openai.com/codex/config-basic))

Add this to `~/.codex/config.toml` or `.codex/config.toml`:

```toml
[mcp_servers.hexabot]
url = "http://localhost:3000/api/mcp"
bearer_token_env_var = "HEXABOT_MCP_TOKEN"
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60
```

Then run Codex from your Hexabot project:

```bash
codex
```

Example prompt:

```txt
Use the Hexabot MCP server and the Hexabot workflow writer skill.
Inspect the available workflow schema, then generate a workflow that qualifies a lead, stores the user email in memory, and creates a CRM ticket through an action.
```

***

### 4.3 OpenCode

OpenCode uses JSON/JSONC configuration. You can define MCP servers under the `mcp` key, either globally in:

```txt
~/.config/opencode/opencode.json
```

or per project in:

```txt
opencode.json
```

OpenCode remote MCP servers use `type: "remote"`, `url`, optional `headers`, and an `enabled` flag. It also supports disabling OAuth auto-detection when using API-key-style bearer tokens. ([OpenCode](https://opencode.ai/docs/config/))

Create or update `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hexabot": {
      "type": "remote",
      "url": "http://localhost:3000/api/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:HEXABOT_MCP_TOKEN}"
      }
    }
  }
}
```

Verify:

```bash
opencode mcp list
opencode mcp debug hexabot
```

Then prompt OpenCode:

```txt
Use the Hexabot action creator skill and the Hexabot MCP server.
Create a new Hexabot action named crm-ticket-create that accepts firstname, lastname, email, phone, category, and description, then calls a CRM REST API.
```

***

### 4.4 Cursor

Cursor supports MCP servers through `.cursor/mcp.json` for project configuration or `~/.cursor/mcp.json` for global configuration. Cursor’s MCP docs show remote servers configured with `url` and optional `headers`, and it supports environment interpolation such as `${env:NAME}` in `url` and `headers`. ([Cursor](https://cursor.com/docs/mcp.md?utm_source=chatgpt.com))

Create:

```txt
.cursor/mcp.json
```

Add:

```json
{
  "mcpServers": {
    "hexabot": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HEXABOT_MCP_TOKEN}"
      }
    }
  }
}
```

Then in Cursor:

1. Open Cursor Settings.
2. Go to MCP / Model Context Protocol.
3. Confirm that `hexabot` is listed.
4. Enable it if needed.
5. Open Agent mode and ask Cursor to use Hexabot MCP.

Example prompt:

```txt
Use the Hexabot MCP server and the installed Hexabot workflow writer skill.
Generate a workflow YAML for a support triage agent that detects the customer issue, asks for missing information, and triggers an action to open a ticket.
```

***

### 4.5 Windsurf / Cascade

Windsurf Cascade supports MCP through the Cascade MCP settings and the raw config file:

```txt
~/.codeium/windsurf/mcp_config.json
```

For remote HTTP MCP servers, Windsurf uses `serverUrl` or `url`, plus optional `headers`. It also supports environment interpolation in `serverUrl`, `url`, and `headers`. ([Windsurf Docs](https://docs.windsurf.com/windsurf/cascade/mcp))

Open Windsurf settings, then go to:

```txt
Windsurf Settings > Cascade > MCP Servers
```

Or edit the raw config file:

```json
{
  "mcpServers": {
    "hexabot": {
      "serverUrl": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HEXABOT_MCP_TOKEN}"
      }
    }
  }
}
```

After saving, refresh the MCP servers in Windsurf.

Example prompt:

```txt
Using the Hexabot MCP server, inspect the available tools and generate a Hexabot action for sending a WhatsApp template message. Follow the Hexabot action creator skill.
```

***

### 4.6 VS Code + GitHub Copilot Chat

VS Code stores MCP configuration in:

```txt
.vscode/mcp.json
```

or in the user profile. VS Code uses a top-level `servers` object, not `mcpServers`, and supports HTTP MCP servers with `type: "http"`, `url`, and `headers`. It also supports `inputs` for sensitive values such as API keys and tokens. ([Visual Studio Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration))

Create:

```txt
.vscode/mcp.json
```

Add:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "hexabot-mcp-token",
      "description": "Hexabot MCP Token",
      "password": true
    }
  ],
  "servers": {
    "hexabot": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:hexabot-mcp-token}"
      }
    }
  }
}
```

Then:

1. Save `.vscode/mcp.json`.
2. Click **Start** in the MCP config file.
3. Open Copilot Chat.
4. Select **Agent** mode.
5. Confirm the MCP tools are visible from the tools menu.

GitHub’s MCP setup docs describe this flow: save the MCP config, start the server, open Copilot Chat, select Agent mode, and inspect available tools. ([GitHub Docs](https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-chat-with-mcp))

### 4.7 Cline

Cline stores MCP settings in:

```txt
cline_mcp_settings.json
```

Cline supports local stdio MCP servers and remote servers configured with `url`, `headers`, `disabled`, and optional tool approval settings. ([Cline Documentation](https://docs.cline.bot/mcp/adding-and-configuring-servers?utm_source=chatgpt.com))

Open Cline’s MCP settings:

```txt
MCP Servers > Configure > Configure MCP Servers
```

Add:

```json
{
  "mcpServers": {
    "hexabot": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer <HEXABOT_MCP_TOKEN>"
      },
      "disabled": false
    }
  }
}
```

Then ask Cline:

```txt
Use the Hexabot MCP server.
Create a production-ready Hexabot workflow for lead qualification, then generate any missing actions required by the workflow.
```

For Cline, prefer storing this in the user-level Cline settings rather than committing it to the project repository.

***

## 5. Suggested prompts for building Hexabot actions and workflows

### Generate a new action

```txt
Use the Hexabot action creator skill and the Hexabot MCP server.

Create a new Hexabot action named crm-ticket-create.

Requirements:
- Inputs: firstname, lastname, email, phone, category, description
- Validate required fields
- Call a CRM REST API
- Return a structured success or error result
- Follow the existing Hexabot action architecture
- Add tests if the project has an existing test pattern
```

### Generate a new workflow

```txt
Use the Hexabot workflow writer skill and the Hexabot MCP server.

Create a workflow named support-triage.

The workflow should:
- Greet the user
- Detect the support category
- Ask for missing customer information
- Store firstname, lastname, and email in memory
- Call an action to create a support ticket
- Confirm the ticket reference to the user
- Include fallback handling when the user message is unclear
```

### Review an existing workflow

```txt
Use the Hexabot MCP server to inspect the current workflow schema.

Review this workflow for:
- Invalid fields
- Missing bindings
- Missing action references
- Broken transitions
- Missing fallback paths
- Unsafe assumptions
- Opportunities to simplify the workflow
```

### Generate action + workflow together

```txt
Use both Hexabot skills:
- hexabot-action-creator
- hexabot-workflow-writer

Goal:
Build an end-to-end demo workflow for an AI sales assistant.

Steps:
1. Inspect the available Hexabot workflow and action patterns through MCP.
2. Propose the required actions.
3. Generate the action code.
4. Generate the workflow YAML.
5. Validate the workflow against the available schema.
6. Explain how to test it locally.
```

***

## 6. Recommended development workflow

Use this workflow when asking an AI coding agent to build Hexabot automation:

```txt
1. Inspect
   Ask the agent to inspect existing Hexabot action and workflow examples.

2. Plan
   Ask it to propose the action inputs, outputs, workflow states, bindings, and memory usage.

3. Generate
   Ask it to generate the action code and workflow definition.

4. Validate
   Ask it to validate against Hexabot MCP schemas/tools.

5. Test
   Ask it to add or run relevant tests.

6. Review
   Review generated code manually before committing.

7. Commit
   Commit action and workflow files separately for easier review.
```

***

## 7. Security recommendations

Keep MCP tokens out of Git. Prefer environment variables, input prompts, or user-level config files. VS Code, Cursor, Claude Code, and Windsurf all provide mechanisms to avoid hardcoding secrets in project files. ([Visual Studio Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration))

Use a dedicated Hexabot MCP token for AI coding tools. If the token is leaked, revoke it from the Hexabot profile page and generate a new one.

Treat MCP tools as powerful integrations. MCP authorization is strongly recommended when servers access user-specific data, perform audited operations, or expose administrative capabilities. ([Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/security/authorization?utm_source=chatgpt.com))

For shared repositories, commit only safe config templates, for example:

```json
{
  "mcpServers": {
    "hexabot": {
      "type": "http",
      "url": "${HEXABOT_MCP_URL:-http://localhost:3000/api/mcp}",
      "headers": {
        "Authorization": "Bearer ${HEXABOT_MCP_TOKEN}"
      }
    }
  }
}
```

Never commit:

```txt
Real MCP tokens
Production API keys
Customer data
Private CRM credentials
```

***

## 8. Troubleshooting

### The agent cannot see Hexabot tools

Check that Hexabot is running:

```bash
curl http://localhost:3000/api/mcp
```

Then restart or refresh the MCP server from your agent.

For VS Code, use:

```txt
MCP: List Servers
MCP: Reset Cached Tools
```

VS Code provides MCP commands for listing servers, opening configuration, browsing resources, and resetting cached tools. ([Visual Studio Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration))

### Authentication fails

Check that the token is exported:

```bash
echo $HEXABOT_MCP_TOKEN
```

Then regenerate the token from:

```txt
http://localhost:3000/profile
```

### Cursor or Windsurf does not load the server

Check the config file location:

```txt
Cursor project config: .cursor/mcp.json
Cursor global config: ~/.cursor/mcp.json

Windsurf config: ~/.codeium/windsurf/mcp_config.json
```

Cursor supports both project and global MCP config files; Windsurf uses `~/.codeium/windsurf/mcp_config.json`. ([Cursor](https://cursor.com/docs/mcp.md?utm_source=chatgpt.com))

### Codex does not load the server

Check the TOML file:

```txt
~/.codex/config.toml
.codex/config.toml
```

Then ensure the server block is named correctly:

```toml
[mcp_servers.hexabot]
url = "http://localhost:3000/api/mcp"
bearer_token_env_var = "HEXABOT_MCP_TOKEN"
enabled = true
```

### OpenCode does not authenticate

Run:

```bash
opencode mcp list
opencode mcp debug hexabot
```

If you use a bearer token instead of OAuth, keep:

```json
"oauth": false
```

OpenCode supports debugging MCP authentication and disabling OAuth auto-detection for API-key-style servers. ([OpenCode](https://opencode.ai/docs/mcp-servers/))

***

## 9. Minimal recommended setup for your docs

For Hexabot documentation, I would present Claude Code, Codex, OpenCode, Cursor, and Windsurf as first-class examples, then add VS Code Copilot and Cline as secondary MCP-compatible setups.

The simplest “golden path” is:

```bash
npx skills add hexabot-ai/hexabot-action-creator
npx skills add hexabot-workflow-writer

export HEXABOT_MCP_URL="http://localhost:3000/api/mcp"
export HEXABOT_MCP_TOKEN="paste-your-token-here"
```

Then configure the agent with:

```txt
MCP server name: hexabot
MCP server URL:  http://localhost:3000/api/mcp
Header:          Authorization: Bearer <HEXABOT_MCP_TOKEN>
```

Once connected, the user can prompt:

```txt
Use the Hexabot MCP server and the installed Hexabot skills to create a new action and workflow for the following use case...
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hexabot.ai/quickstart/using-ai-coding-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.