create-connector

Create a Connector

We're going to create a new connector spec for $0. The connector will enable Kibana to interact with the third-party service and expose operations as tools for AI agents.

Reference Materials

• reference/connector-patterns.md — Directory structure, file templates, and registration patterns

Step 1: Determine the Connector Strategy

Check if $0 has an official hosted MCP server. If so, creating an MCP-native connector is preferred.

MCP server available? → Read reference/mcp-connector-setup.md and follow its steps.

No MCP server available? → Read reference/custom-connector-setup.md and follow its steps.

Follow only the steps for the chosen path. Do not mix them.

Step 2: Create the Connector Spec

Create the connector spec in src/platform/packages/shared/kbn-connector-specs/src/specs/{connector_name}/.

Follow the patterns in reference/connector-patterns.md:

1. {connector_name}.ts — ConnectorSpec definition with metadata, auth, schema, and actions
2. types.ts — Zod input schemas and inferred TypeScript types for each action
3. {connector_name}.test.ts — Unit tests
4. icon/index.tsx — Brand icon component

Register in src/platform/packages/shared/kbn-connector-specs/src/all_specs.ts and connector_icons_map.ts.

Replace the placeholder icon with a proper brand icon. Search for existing SVG/PNG files in:

• src/platform/packages/shared/kbn-connector-specs/src/specs/*/icon/
• x-pack/platform/plugins/shared/stack_connectors/public/connector_types/{connector}/

Step 3: Write LLM-Quality Descriptions and Skill Content

AI agents rely on descriptions to choose the right action and construct valid inputs. Every action and parameter must have high-quality descriptive text.

isTool and action descriptions

Actions should set isTool: true to be discoverable by AI agents in Agent Builder. This is the default for most actions. Use isTool: false only for actions that should not be invoked autonomously (e.g. destructive or admin-only operations).

Every entry MUST have a description field (plain string, NOT i18n.translate()) that explains:

• What the action does
• When an agent should use it (vs. other actions)
• What it returns
• For download/binary actions: a WARNING about large base64 payloads and the need for post-processing

Parameter descriptions

Every Zod parameter in input schemas MUST have a .describe() call that includes:

• What the parameter controls
• Concrete examples or allowed values
• Any constraints (format, length, required vs. optional behavior)

See the ServiceNow, Slack, and GitHub connector specs for examples of strong description quality.

The skill property

Add a skill property to the ConnectorSpec — a markdown string providing higher-level LLM guidance:

• Multi-step workflow patterns (e.g., "to create an incident, first call X, then Y")
• Common gotchas and error cases
• Best practices for the service

Use the [...].join('\n') pattern to keep the string readable in source:

skill: [
  '## $0 Connector',
  '',
  'Use this connector to ...',
  '',
  '### Common patterns',
  '- To do X, first call `actionA` then `actionB`',
].join('\n'),

Step 4: Create Tests

Add tests following the existing examples:

1. Connector spec tests — See google_drive/google_drive.test.ts or slack/slack.test.ts for the pattern.

You do not need to execute the tests — just create the files.

Step 5: Write Documentation

Create a connector doc page in docs/reference/connectors-kibana/{name}-action-type.md.

Prerequisites

This step requires documentation skills from https://github.com/elastic/elastic-docs-skills. Check availability by invoking docs-check-style (use the Skill tool). If it fails with "skill not found", stop and tell the user:

Documentation skills are not installed. Please install them:

curl -sSL https://raw.githubusercontent.com/elastic/elastic-docs-skills/main/install.sh | bash

Then re-run this step.

Write the doc page

1. Read 1-2 existing connector docs from docs/reference/connectors-kibana/ as templates (for example, zendesk-action-type.md, jira-cloud-action-type.md). Follow the same structure.
2. Write the new doc page. Use docs-syntax-help if unsure about MyST Markdown syntax.
3. Run these skills on the new file and fix any issues:
   • frontmatter-description — generate the description frontmatter field
   • page-opening-optimizer — verify H1 and opening paragraph
   • applies-to-tagging — validate applies_to block
   • docs-check-style — check Elastic style guide compliance

Update navigation and listings

1. Add an entry in docs/reference/toc.yml under the connectors section.
2. Add a row in docs/reference/connectors-kibana/_snippets/elastic-connectors-list.md.

Once you are done developing the connector spec, tests, and documentation, let the user review your work before next steps.

Important Notes

• Stop if architectural gaps emerge — This skill is for adding connectors to the catalog, not for enhancing platform features
• Write rich descriptions — Every action and parameter must have descriptive text that helps LLMs choose the right action and construct valid inputs; add a skill property with multi-step patterns and gotchas
• Follow existing patterns — Look at Slack, GitHub, Google Drive, and ServiceNow connectors for reference
• DO NOT modify existing documentation — There may be existing connectors with similar names. Do not modify their documentation files.