Preview — in active development. The Stacktape MCP server is under active development. Available tools, safety behavior, and integration details may change between releases.
Stacktape includes built-in support for AI coding assistants through an MCP server for deploying, inspecting, and debugging stacks from your editor; an agent mode that exposes an HTTP API for iterative local development; and an mcp add command for registering the MCP server with supported editors. AI coding assistants can also use Stacktape docs and project context to help draft or edit stacktape.ts configuration files.
Start here
For most users, the shortest path is:
It connects the coding agents installed on your machine (Claude Code, Codex, Cursor, VS Code, Copilot CLI, Windsurf and OpenCode) to Stacktape: it adds the Stacktape MCP server to each one you pick, then checks that the server starts. Start a new session in your agent and ask it to “use Stacktape to show what this project deploys.” The agent gets five tools: stacktape_incident, stacktape_docs, stacktape_project, stacktape_cli and stacktape_dev. See MCP server setup for what it changes, manual setup and troubleshooting.
The AI-assisted development workflow
An AI coding assistant working with Stacktape follows a build-test-deploy loop. The assistant writes your infrastructure config, starts a local dev environment, implements application code, reads logs to fix errors, and deploys when everything works. What makes this effective is the feedback loop — the AI observes what's happening and iterates until the stack works correctly.
Generate config
AI writes stacktape.ts from your requirements or existing codebase
Start dev mode
Agent mode launches local workloads with an HTTP API
Write application code
AI implements handlers, services, and business logic
Test and iterate
AI reads logs, queries databases, triggers rebuilds, and fixes errors
Deploy
AI deploys the working stack to AWS via the MCP server
The assistant writes or edits the config in step 1 using Stacktape docs for reference. Agent mode powers steps 2–4. The MCP server orchestrates step 5 and provides documentation context throughout.
MCP server
The Stacktape MCP server gives AI coding assistants direct access to Stacktape operations through the Model Context Protocol. Instead of asking the assistant to run raw shell commands itself, the MCP server plans and runs Stacktape CLI operations through structured tools with validation, safety gates, and credential handling. The server runs locally via stdio transport and reuses your existing Stacktape CLI authentication.
The server exposes five tools:
| Tool | Purpose | Typical use |
|---|---|---|
stacktape_incident | Fetch an incident's context or find incidents | Start an incident investigation with signals, evidence, release changes, history and the AI assessment |
stacktape_docs | Search and fetch Stacktape documentation | Config syntax, resource types, deployment patterns, troubleshooting |
stacktape_project | Inspect a local Stacktape project | Discover config files, parse package.json scripts, infer CLI defaults |
stacktape_cli | List, describe, plan, and run CLI commands | Deploy, preview changes, read logs, query databases, manage secrets |
stacktape_dev | Control dev mode lifecycle | Start, stop, check status, read logs, rebuild workloads |
How assistants use the MCP server
An assistant investigating an incident starts with stacktape_incident, which returns the incident's context in one call. It then reads what it needs through stacktape_cli: read-only, diagnostic and local commands such as logs, metrics, status and aws call run directly with action=run and validated arguments, without a plan or your confirmation. action=list and action=describe help it find commands and their arguments.
This is the local path: your assistant on your machine. For a hosted run instead, the Console can start a coding agent (Claude Code, Codex, Grok or OpenCode) on the project's runner to investigate an incident or propose a fix as a draft pull request, funded by your organization's API key with the agent's provider or your own subscription. See AI assessment, investigation and fixes.
Changes follow a plan-then-execute pattern. Before a mutating command, the assistant calls stacktape_cli with action=plan, which scans your project, resolves config files, validates arguments, and returns a run payload. It then calls action=run with that payload, adding confirm: true only after receiving explicit user approval in the same conversation. Destructive commands go further — the assistant cannot supply confirmation on its own; the MCP server requires direct user confirmation through the client's confirmation form before execution. This flow prevents the assistant from running changes with wrong arguments or against the wrong stage.
The stacktape_docs tool gives the assistant access to the full Stacktape documentation index. When you ask "how do I add a DynamoDB table?" or "what's the syntax for connecting resources?", the assistant searches the docs and returns grounded answers with code examples — rather than guessing from training data.
The stacktape_dev tool controls dev mode lifecycle without requiring an interactive terminal. The assistant can start agent mode, read logs, trigger workload rebuilds, and stop the session — all through structured JSON rather than terminal output parsing.
Safety model
The MCP server categorizes every CLI command by safety level and enforces appropriate gates:
| Safety level | Behavior | Examples |
|---|---|---|
readOnly | Runs without confirmation | status, stack list, logs, metrics |
diagnostic | Runs without confirmation | query sql, query dynamodb, query redis, query opensearch |
local | Runs without confirmation | synth, validate, package |
mutating | Requires explicit user approval (confirm: true) | deploy, secret set, domain add |
destructive | Requires direct user confirmation for the exact command and target | delete, secret delete |
interactive | Rejected — must use user's terminal or stacktape_dev | dev, init |
Read-only commands run without confirmation. Diagnostic database commands also run without confirmation, because the server accepts only read operations for them and refuses anything else. Mutating commands require the user to explicitly approve execution in the current conversation. Destructive commands go further: the assistant cannot supply confirmation on its own. Instead, the MCP server presents a confirmation dialog directly to the user, and the operation proceeds only if the user confirms the exact command and target. If the MCP client does not support confirmation forms, destructive commands are refused entirely and the user is told to run them in their own terminal.
Interactive commands like stacktape dev and stacktape init require a terminal UI and are rejected by stacktape_cli. Dev mode lifecycle is handled through the dedicated stacktape_dev tool instead.
Credential handling
The MCP server rejects raw Stacktape credential arguments passed through the AI assistant, masks sensitive output (secrets, passwords, API keys, connection strings) before returning results, and instructs assistants not to read credential files or ask for API keys in chat. The MCP server reuses the Stacktape CLI authentication state. If execution fails with an auth error, the server directs the user to run stacktape login in their own terminal. For CI, configure a dedicated STACKTAPE_API_KEY secret outside the conversation rather than passing credentials through chat or MCP arguments.
For full setup instructions, see the MCP server setup guide.
Agent mode
Agent mode is a variant of Stacktape's dev mode designed for programmatic control by AI coding assistants. It starts a long-lived local process via stacktape dev --agent and exposes an HTTP API on a configurable loopback port (default 7331). Every request must carry the session token stored in ~/.stacktape/dev-agent-tokens/{port}.token. While standard dev mode uses an interactive terminal UI, agent mode returns structured JSON responses. When the MCP stacktape_dev tool plans agent mode, it defaults the stage to dev and can infer configPath from the project scan, but the final start arguments must include stage, region, and configPath.
Agent mode controls Stacktape dev mode through HTTP endpoints for status, logs, rebuilds, stop, and local database inspection. It provides structured JSON endpoints for:
- Status checks — workload health, ports, and readiness phase (
starting,ready,rebuilding,stopping,stopped) - Log reading — HTTP
GET /logsreturns the local JSONL file path. Read the file for raw HTTP integration; MCPstacktape_devwithaction: "logs"reads it and provides cursor pagination and filters - Workload rebuilds — trigger rebuilds of specific workloads or all workloads after code changes
- Database queries — execute SQL, Redis commands, and DynamoDB operations against locally emulated PostgreSQL, MySQL, Redis, and DynamoDB databases
The stacktape_dev MCP tool controls the session lifecycle: plan, start, status, logs, rebuild a specific workload, rebuild all workloads, and stop. Agent mode also exposes HTTP endpoints for querying local PostgreSQL, MySQL, Redis, and DynamoDB databases — see Agent mode in dev for the endpoint reference. For querying deployed (remote) databases in production or staging stacks, use stacktape query sql, stacktape query redis, stacktape query dynamodb, or stacktape query opensearch through the MCP server's stacktape_cli tool.
When to use agent mode
Use agent mode when an AI assistant needs to iterate on your application — writing code, testing it, reading errors, and fixing issues in a loop. The HTTP endpoints for logs, status, and database queries let the assistant self-correct without human intervention.
When NOT to use agent mode
If you're developing interactively (not through an AI assistant), standard dev mode with its terminal UI is a better fit. Dev mode provides the same local development capabilities with a human-friendly interface.
For the full HTTP API reference and usage, see Agent mode in dev.
AI config generation
An AI coding assistant can use Stacktape documentation and project context to help draft or edit a stacktape.ts configuration file based on your requirements. The stacktape init command is an interactive setup command that must be run in the user's own terminal — it is classified as interactive and rejected by the MCP server's stacktape_cli tool.
To generate a config from an existing codebase, run stacktape init in the repository: it reads the code, proposes the infrastructure and writes the config after you review it.
Coding assistant setup
The stacktape mcp add command connects your coding agents to Stacktape in one step. See the MCP server setup guide for each agent and for manual setup.
The stacktape mcp command starts a local stdio MCP server. Clients that support launching local stdio MCP servers can connect to it.
Choosing the right approach
| Feature | MCP server | Agent mode | Config generation | mcp add |
|---|---|---|---|---|
| What it does | Structured Stacktape operations from your editor | HTTP API for iterative local development | Generate stacktape.ts from your codebase | Register MCP server in your editor |
| When to use | Ongoing development with AI | AI-driven build-test-fix loops | Starting a new Stacktape project | One-time setup per editor |
| Can deploy to AWS | ✓ | ✕ | ✕ | ✕ |
| Reads logs | Deployed stacks | Local dev | ✕ | ✕ |
| Queries databases | Deployed databases | Local databases | ✕ | ✕ |
For most teams, run stacktape mcp add once to set up your editor, then use the MCP server for day-to-day work. The MCP server handles documentation lookup, CLI execution, and dev mode control through a single integration. Agent mode is useful when the AI assistant needs to run a sustained development loop — starting dev mode, writing code, reading logs, and iterating until the application works.
Using Stacktape with AI FAQ
Which AI coding assistants work with Stacktape?
Stacktape works with any MCP-compatible coding assistant. stacktape mcp add sets up Claude Code, Codex, Cursor, VS Code with GitHub Copilot, GitHub Copilot CLI, Windsurf and OpenCode. For any other assistant, point it at the command stacktape with the argument mcp. See MCP server setup for each agent's configuration.
Can an AI assistant deploy to production through the MCP server?
Yes, with safety gates — though the MCP server is still in preview and under active development. Mutating commands that change AWS resources require explicit user approval (confirm: true) and run through stacktape_cli only after planning. Destructive operations like stacktape delete go further: they require direct user confirmation for the exact command and target that the AI assistant cannot supply on its own, and if the client doesn't support confirmation forms they are refused entirely. The output of secret commands such as secret get and known credential patterns, such as API keys and connection strings with passwords, are masked in MCP responses; other data an assistant reads, such as log lines, comes back as it is.
How does agent mode differ from standard dev mode?
Standard dev mode runs an interactive terminal UI designed for human developers. Agent mode starts a long-lived local process (stacktape dev --agent) with an HTTP API designed for programmatic access by AI assistants. Both modes run workloads locally and support rebuilds after code changes. Agent mode adds structured JSON endpoints for status, logs, rebuilds, and database queries that AI assistants can consume without parsing terminal output. See Agent mode in dev for the full API reference.
Does the MCP server require separate authentication?
No. The MCP server reuses the Stacktape CLI authentication state. If execution fails with an auth error, run stacktape login in your own terminal. For CI, configure a dedicated STACKTAPE_API_KEY secret outside the conversation rather than passing credentials through chat. The MCP server rejects raw credential arguments passed through the AI assistant and instructs assistants not to ask for API keys in chat.
What databases can AI assistants query through agent mode?
Agent mode exposes HTTP endpoints for querying locally emulated PostgreSQL, MySQL, Redis, and DynamoDB databases. See the agent mode guide for the endpoint reference. For querying deployed (remote) databases, use stacktape query sql, stacktape query redis, stacktape query dynamodb, or stacktape query opensearch through the MCP server's stacktape_cli tool.
MCP server vs running Stacktape CLI in a terminal — what's the difference?
The MCP server adds structured safety gates, argument validation, project scanning, sensitive-value masking, and documentation context on top of the same CLI operations. When an AI assistant uses the MCP server, it gets validated argument schemas, automatic config file discovery, safety-appropriate confirmation flows, and masked output — none of which are available when the assistant runs raw shell commands. The MCP server also prevents the assistant from running interactive commands or accepting raw credential arguments.