core-ai AGENTS.md

Core AI — Agent Instructions

This file is the Layer A harness for Codex CLI and other OpenAI-compatible agents. Skills in .agents/skills/ provide the domain expertise (Layer B).

Repository Overview

This monorepo contains Helius developer tools for building on Solana:

Package	What it does
helius-mcp/	MCP server (npx helius-mcp@latest) — exposes 10 public tools total: 9 routed domain tools plus expandResult
helius-skills/	Canonical skill source — SKILL.md + reference files for each domain
helius-plugin/	Claude Code plugin — bundles skills + auto-starts MCP server
helius-cli/	CLI for account setup, blockchain queries, and staking (npx helius-cli@latest)

MCP Server Setup

The Helius MCP server provides live blockchain access through 10 public tools total: 9 routed domain tools plus expandResult. Configure it as an MCP tool source:

npx helius-mcp@latest

This works with any MCP-compatible client. Use a domain tool such as heliusWallet, heliusAsset, or heliusStreaming plus action: "getBalance", action: "getAssetsByOwner", or action: "createWebhook" to call a specific Helius action. Use expandResult for summary-first follow-ups.

For Codex, run codex mcp add helius -- npx helius-mcp@latest or add to .codex/config.toml (or ~/.codex/config.toml for global):

[mcp_servers.helius]
command = "npx"
args = ["helius-mcp@latest"]

For other MCP clients, add to your project's .mcp.json:

{
  "mcpServers": {
    "helius": {
      "command": "npx",
      "args": ["helius-mcp@latest"]
    }
  }
}

API Key Setup

Most tools require a Helius API key. Three paths:

Path A — Existing key: Set the HELIUS_API_KEY environment variable, or call the setHeliusApiKey MCP tool.

Path B — Signup: Call generateKeypair → signup with mode: "link" (returns a hosted paymentUrl the user opens in a browser) → after payment, signup with mode: "resume". Or mode: "autopay" to pay USDC from the local keypair (wallet must hold ~0.001 SOL + the plan amount in USDC). API key is configured automatically.