AI Agent Configuration

The GxP Toolkit includes pre-configured agent files for popular AI coding assistants. These agents understand the GxP architecture and can help you build plugins more effectively.

Planning Agent

The platform-native planning agent — the one you talk to inside the developer hub — runs server-side (not in your IDE) and is responsible for:

• Leading the planning conversation, asking the clarifying questions needed to scope the work.
• Producing the structured plan document the coding agent executes against.
• Grounding the plan in real GXP conventions (store-only API calls, ComponentKit primitives, no raw Echo, etc.).
• Capturing every requirement and decision into a transcript super-admins can review later.

The planning agent is depersonified: it has no name, no persona, and responds with technical updates only — no greetings or pleasantries. The IDE-side agents below (Claude Code, Codex, Gemini) are separate — they live in your local workspace and help you write code against the plan the planning agent produced.

Overview

When you create a new project with gxdev init, the following AI configuration files are automatically included:

File	AI Tool	Purpose
.claude/agents/gxp-developer.md	Claude Code	Subagent for GxP development
.claude/settings.json	Claude Code	MCP server configuration
AGENTS.md	OpenAI Codex	Agent instructions
GEMINI.md	Google Gemini	Code Assist instructions

What the Agents Know

All agents are configured to understand:

1. GxP Architecture - The runtime container model where your Plugin.vue runs inside the platform environment
2. Store Integration - How to use gxpPortalConfigStore for strings, settings, assets, and state
3. API Calls - The correct way to make API requests through the store (never raw axios/fetch)
4. WebSocket Events - How to listen for and emit real-time events
5. Component Kit - Available UI components from @gxp-dev/app-ui
6. Vue Directives - Using gxp-string and gxp-src for dynamic content

Claude Code Setup

Subagent

The .claude/agents/gxp-developer.md file defines a specialized GxP developer subagent. Claude Code automatically discovers this agent and can use it when working on your project.

To invoke the agent:

Use the gxp-developer agent to help with this component

MCP Servers

The toolkit registers two MCP (Model Context Protocol) servers in template/mcp.json (copied to .mcp.json / .claude/settings.json / .gemini/settings.json / AGENTS.md-aware tooling on gxdev init):

1. gxp-api — stdio. Always available. Provides API spec lookups from the OpenAPI / AsyncAPI definitions for the configured environment.
2. gxp-appui-storybook — HTTP at http://localhost:6006/mcp. Served by @storybook/addon-mcp inside @gxp-dev/app-ui. There is no hosted endpoint — the server is local-only, live only while npm run storybook (or gxdev storybook) is running in the plugin project's directory. When storybook isn't running, agent clients that auto-connect to every server in mcp.json will see a connection-refused on localhost:6006; that's expected and non-fatal — the rest of the agent (and the gxp-api server) keeps working without it. Start storybook the moment you need AppUI discovery and re-prompt the agent.

Combined configuration:

{
  "mcpServers": {
    "gxp-api": {
      "command": "mcp-serve",
      "args": [],
      "env": {}
    },
    "gxp-appui-storybook": {
      "type": "http",
      "url": "http://localhost:6006/mcp"
    }
  }
}

gxp-api tools (stdio)

Tool	Description
get_openapi_spec	Fetch the complete OpenAPI specification
get_asyncapi_spec	Fetch the AsyncAPI specification for WebSocket events
search_api_endpoints	Search endpoints by path, summary, or tags
search_websocket_events	Search WebSocket channels and events
get_endpoint_details	Get detailed info about a specific endpoint
get_api_environment	Get current environment configuration

The MCP server reads VITE_API_ENV from your .env file to determine which API environment to use.

gxp-appui-storybook tools (HTTP)

Tool	Description
preview-stories	Render a AppUI story so the agent can see what a component looks like with given props
get-storybook-story-instructions	Pull the structured instructions that document how to use a component
get-documentation	Fetch a specific AppUI documentation page
list-all-documentation	Enumerate every documentation page available
run-story-tests	Execute the story-level interaction / accessibility tests

The toolkit's previous list_appui_components tool has been removed. AppUI and story discovery now flow entirely through the storybook server's tools above. Agent instructions reference those rather than the old toolkit tool.

Prerequisite: keep storybook running locally during AI-assisted work:

gxdev storybook
# or
npm run storybook

When the agent attempts a storybook tool and the server isn't running, it'll surface a clear connection error — start storybook and retry.

OpenAI Codex Setup

The AGENTS.md file at the project root provides instructions for OpenAI Codex CLI. Codex automatically reads this file when working in your project directory.

Key sections in the agent file:

• Architecture overview
• Store usage patterns
• API call guidelines
• WebSocket event handling
• Available components

Google Gemini Setup

The GEMINI.md file provides concise instructions for Gemini Code Assist. This format is optimized for Gemini's context handling.

API Documentation URLs

The agents reference API specs from these endpoints based on your environment:

Environment	OpenAPI	AsyncAPI
develop	api.zenith-develop.env.eventfinity.app/api-specs/openapi.json	api.zenith-develop.env.eventfinity.app/api-specs/asyncapi.json
staging	api.efz-staging.env.eventfinity.app/api-specs/openapi.json	api.efz-staging.env.eventfinity.app/api-specs/asyncapi.json
production	api.gramercy.cloud/api-specs/openapi.json	api.gramercy.cloud/api-specs/asyncapi.json

Critical Rules for AI Assistants

The agent files emphasize these critical rules:

1. Never Use Raw HTTP Clients

// WRONG - Never do this
const response = await axios.get("/api/v1/attendees")
const data = await fetch("/api/v1/attendees")

// CORRECT - Always use the store
const store = useGxpStore()
const data = await store.apiGet("/api/v1/attendees")

2. Use Store API Methods

The store handles:

• Authentication token injection
• Base URL configuration per environment
• CORS proxy in development
• Error handling

// Available methods
await store.apiGet("/endpoint", { params })
await store.apiPost("/endpoint", data)
await store.apiPut("/endpoint/id", data)
await store.apiPatch("/endpoint/id", data)
await store.apiDelete("/endpoint/id")

3. Use Dynamic Content Directives

<!-- Text from strings -->
<h1 gxp-string="welcome_title">Default Title</h1>

<!-- Text from settings -->
<span gxp-string="company_name" gxp-settings>Company</span>

<!-- Images from assets -->
<img gxp-src="hero_image" src="/placeholder.jpg" />

4. WebSocket Events Through Store

// Listen for events
store.listenSocket("primary", "EventName", (data) => {
	console.log("Received:", data)
})

// Emit events
store.emitSocket("primary", "event-name", { data: "value" })

Customizing Agent Files

You can customize the agent files for your specific project:

1. Add project-specific patterns - Document your component conventions
2. Include API usage examples - Add examples relevant to your plugin
3. Reference custom dependencies - List any additional libraries you use

Example customization in AGENTS.md:

## Project-Specific Patterns

This plugin uses the following conventions:

- All views are in `src/views/`
- Composables are in `src/composables/`
- The main API endpoints we use are:
  - GET /api/v1/events/{id}/attendees
  - POST /api/v1/check-ins

Troubleshooting

MCP Server Not Working

1. Ensure mcp-serve is in your PATH:

   which mcp-serve

   (The legacy gxp-api-server bin still ships as a deprecation shim that forwards to mcp-serve and writes a notice to stderr.)

2. Test the server manually:

   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mcp-serve

3. Check your .env file has a valid VITE_API_ENV value

gxp-appui-storybook (http)

1. Confirm storybook is running:

   curl http://localhost:6006/mcp -X POST \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

   A Connection refused here means storybook isn't running — start it with gxdev storybook or npm run storybook.

2. If storybook is running on a non-default port, update the url in .mcp.json / .claude/settings.json to match.

3. Restart your agent (Claude Code, Codex, etc.) after starting storybook — most clients only attempt MCP connections on launch.

Agent Not Being Used

For Claude Code:

• Ensure .claude/agents/gxp-developer.md exists
• The file must have valid YAML frontmatter

For Codex:

• Ensure AGENTS.md is at the project root
• Run codex from within the project directory

For Gemini:

• Ensure GEMINI.md is at the project root
• Enable Gemini Code Assist in your IDE