Agent & Developer Tooling

MCP server, agent skills, dev container, and llms.txt — the tools that make Toast agentic-first.

Toast is designed to be worked on by both humans and AI agents. The tooling stack makes project state inspectable, workflows teachable, and the codebase agent-readable.

What contributors actually use day to day

Most contributors only need three things:

td for inspection, scaffolding, and environment checks
the contributor docs themselves via /docs/code/*
the MCP server when working through an AI coding assistant

The rest of this page explains how those pieces fit together.

The tooling stack

llms.txt              Published docs served as agent-readable markdown
  ↑
Agent Skills          19 task-specific instruction sets (.agents/skills/)
  ↑
MCP Server            JSON-RPC tools for project inspection (@toast/mcp)
  ↑
Toast Dev CLI (td)    Pure data functions + human-readable CLI (@toast/td)
  ↑
Codebase              PostgreSQL, Docker Compose, Hono API, pnpm workspace

Each layer builds on the one below. The CLI and MCP server share the same data functions — the CLI formats output as ANSI text for humans; the MCP server returns structured JSON for agents.

The Model Context Protocol server exposes project inspection tools over stdio. AI coding assistants (Claude Code, VS Code Copilot, Cursor, OpenCode) discover it automatically via config files at the repo root.

Available tools

Tool	What it returns
`database_schema`	Tables, columns, types, foreign keys, enums
`list_routes`	API endpoints from the live OpenAPI spec
`database_query`	Read-only SQL results (100-row limit, 5s timeout)
`read_log_entries`	Structured Pino log entries from Docker Compose
`last_error`	Recent error-level log entries with stack traces
`project_info`	Monorepo structure, versions, all workspace packages
`service_status`	Running services and their ports
`migration_status`	Local vs applied migrations (pending, applied, orphaned)
`seed_status`	Row counts per table
`test_status`	Last test run results without re-running tests
`ci_status`	GitHub CI status for a branch

Auto-discovery

Config files for each editor are checked into the repo:

Editor	Config file
Claude Code	`.mcp.json`
VS Code / Copilot	`.vscode/mcp.json`
Cursor	`.cursor/mcp.json`
OpenCode	`opencode.json`

No manual setup needed — open the repo and the MCP tools are available.

Agent Skills (`.agents/skills/`)

Skills are task-specific instruction documents that teach agents how to perform common workflows. When an agent recognizes a task matches a skill, it loads the full instructions automatically.

Toast ships 19 skills:

Skill	When it activates
`api-endpoint`	Adding API endpoints, creating routes, new resources
`database-migration`	Schema changes, new tables, migrations, seeding
`commit`	Writing commit messages, commitlint validation
`vitest`	Writing tests, mocking, coverage, fixtures
`toast-simplify`	Post-change cleanup and code simplification
`td`	Using the Toast Dev CLI
`hono`	Hono server development, API reference lookup
`infrastructure`	Env vars, Docker builds, deployment config
`frontend-design`	UI/UX, component styling, accessibility
`use-railway`	Railway infrastructure operations
`railway-debug`	Debugging Railway deployment failures
`better-auth-*`	Authentication configuration (4 skills)
`organization-*`	Multi-tenant org setup, RBAC
`create-auth-skill`	Scaffolding auth in new projects

Skills reference the td CLI and MCP tools — they tell agents what commands to run and what tools to call for each workflow step.

Dev Container

The repo includes a .devcontainer/ configuration for VS Code Remote Containers and GitHub Codespaces. It provides a one-click development environment with:

Node.js 24, pnpm, Docker-in-Docker
PostgreSQL and MinIO pre-configured
Port forwarding for API (3000), Admin (5173), PostgreSQL (5432), MinIO (9000/9001)
All required environment variables pre-set

# Open in VS Code with Remote Containers extension
code .  # → VS Code detects .devcontainer/ and offers to reopen in container

llms.txt

The documentation site serves all content as agent-readable markdown via the llms.txt protocol:

/llms.txt — index of all documentation pages
/llms.mdx/docs/[...slug] — individual pages as processed markdown

Content negotiation is built in: when an agent requests /docs/* with a markdown-preferring Accept header, the response is transparently rewritten to serve the markdown version.

This means agents can fetch any documentation page as structured text without scraping HTML.