Grid Scaffolding

A ready-to-use, AI-assisted development environment for building on the Grid API — Lightspark's payment infrastructure platform (international payouts, on/off-ramps, account management).

Clone it, run one script, and your AI coding tool (Claude Code, Cursor, or Codex) is wired up to Grid's MCP server, agent skill, and documentation.

Prerequisites

• Node.js (provides npx).
• One of: Claude Code, Cursor, or Codex.
• A Grid account for later — you don't need a token to set up or to read docs and write code. You'll create one at https://app.lightspark.com the first time you use the MCP server (see Credentials). Start read-only + sandbox.

Quickstart

git clone <this-repo> grid-scaffolding
cd grid-scaffolding
./setup.sh

setup.sh will:

1. Install the grid-api agent skill (npx skills add lightsparkdev/grid-api — select your agent when prompted).
2. Create .env from .env.example.
3. Refresh the cached Grid docs in docs/cache/.
4. Generate a gitignored .cursor/mcp.json (once .env is filled) and print the Codex config snippet.

That's it to start — you can now explore the docs and write code with no token.

Credentials (just-in-time)

You don't need any credentials to set up, read the docs, or write code. A token is required only to use the Grid MCP server (search_docs or execute), so you provide one exactly when you first need it — not upfront:

1. First time you use the MCP server (exploring / searching docs): your agent will ask for a token. Create a read-only sandbox token at https://app.lightspark.com and add it where your client's MCP server reads it (.env for Claude Code/Cursor — see Per-client notes; ~/.codex/config.toml for Codex). Running "Help me configure my Grid API credentials" also stores a copy for the skill.
2. First time you run a live execute operation (create a customer, send a payment): a read-only token is rejected, so your agent will ask you to swap in a write-capable sandbox token.
3. Only move to a production token once you understand the operations your agent runs.

The MCP server reads its credentials when your client connects, so after adding or changing a token, reconnect/restart your client (and, for Claude Code, re-export the env vars — see below) so grid_mcp picks it up.

Per-client notes

• Claude Code — .mcp.json is committed and reads ${GRID_CLIENT_ID} / ${GRID_CLIENT_SECRET} from the environment. These must be exported before you launch Claude Code, or the MCP server cannot authenticate (source .env alone is NOT enough — the values must be exported):

  set -a; source .env; set +a
  claude
  

  The grid-api skill separately stores credentials in ~/.grid-credentials for its own use; that store does not feed the grid_mcp MCP server, so the exported env vars above are still required for MCP calls.

• Cursor — setup.sh generates .cursor/mcp.json (gitignored) from .env. Cursor rules live in .cursor/rules/grid.mdc.

• Codex — paste config-templates/codex.config.toml.example into ~/.codex/config.toml and fill in credentials. (Codex's MCP format evolves — verify against current Codex docs if it does not connect.)

Verify

Once you're ready to use the MCP server, ask your agent:

Use the Grid MCP to list supported currencies.

This is the first call that needs a token, so your agent will prompt you for a read-only sandbox one (see Credentials). A successful result confirms both the MCP connection and your credentials.

Security

• Never commit secrets. Real credentials live only in .env (gitignored) and ~/.grid-credentials. Committed configs use env-var references or placeholders.
• Sandbox first. Use a read-only sandbox token while experimenting; only issue write-capable / production tokens once you understand what your agent will do.

What's in here

Path	Purpose
.mcp.json	Claude Code MCP config (env-var refs)
.cursor/	Cursor MCP template + rules
config-templates/	Codex config snippet
CLAUDE.md, AGENTS.md	Agent guidance
docs/grid-context.md	Curated links + credential/env reference
docs/cache/	Cached copies of Grid's llms.txt / llms-full.txt (refresh with ./setup.sh --refresh-docs; agents prefer live docs / search_docs)
setup.sh	One-command setup (--refresh-docs to update cache)