Using AI Coding Agents

This guide explains how to connect AI coding agents such as Claude Code, OpenAI Codex, OpenCode, Cursor, ... to Hexabot through MCP, then use Hexabot-specific skills to generate actions and workflows.

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:

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)

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:

http://localhost:3000/profile

Generate an MCP token from your profile page.

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

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

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

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

Verify the installation:

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)

Recommended project configuration

Create a file at the root of your Hexabot workspace:

.mcp.json

Add:

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

Then run:

claude

Inside Claude Code:

/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)

Alternative CLI setup

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:

~/.codex/config.toml

You can also add project-specific configuration in:

.codex/config.toml

Codex supports MCP server configuration in TOML, including HTTP MCP server URLs and bearer tokens loaded from environment variables. (OpenAI Developers)

Add this to ~/.codex/config.toml or .codex/config.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:

codex

Example prompt:

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:

~/.config/opencode/opencode.json

or per project in:

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)

Create or update opencode.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:

opencode mcp list
opencode mcp debug hexabot

Then prompt OpenCode:

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)

Create:

.cursor/mcp.json

Add:

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

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:

~/.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)

Open Windsurf settings, then go to:

Windsurf Settings > Cascade > MCP Servers

Or edit the raw config file:

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

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:

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

Create:

.vscode/mcp.json

Add:

{
  "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)

4.7 Cline

Cline stores MCP settings in:

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)

Open Cline’s MCP settings:

MCP Servers > Configure > Configure MCP Servers

Add:

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

Then ask Cline:

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

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

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

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

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:

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)

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)

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

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

Never commit:

Real MCP tokens
Production API keys
Customer data
Private CRM credentials

---

8. Troubleshooting

The agent cannot see Hexabot tools

Check that Hexabot is running:

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

Then restart or refresh the MCP server from your agent.

For VS Code, use:

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)

Authentication fails

Check that the token is exported:

echo $HEXABOT_MCP_TOKEN

Then regenerate the token from:

http://localhost:3000/profile

Cursor or Windsurf does not load the server

Check the config file location:

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)

Codex does not load the server

Check the TOML file:

~/.codex/config.toml
.codex/config.toml

Then ensure the server block is named correctly:

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

OpenCode does not authenticate

Run:

opencode mcp list
opencode mcp debug hexabot

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

"oauth": false

OpenCode supports debugging MCP authentication and disabling OAuth auto-detection for API-key-style servers. (OpenCode)

---

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:

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:

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

Once connected, the user can prompt:

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