For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/features/mcp-server.md.

MCP Server

tsdevstack includes a built-in Model Context Protocol (MCP) server that exposes CLI commands and project context to AI agents. This gives tools like Claude Code, Claude Desktop, Cursor, and VS Code Copilot an understanding of your project structure, service configuration, and available workflows, so they can assist you accurately instead of guessing.

Quick start

Add the MCP server to your project's .mcp.json:

{
  "mcpServers": {
    "tsdevstack": {
      "command": "npx",
      "args": ["tsdevstack", "mcp:serve"]
    }
  }
}

Restart your AI client. The tools and resources will be available immediately.

Try it

Once the MCP server is connected, paste this read-only health-check prompt into your AI client. It exercises several query tools at once and gives you a one-shot view of your project's local config, cloud deployments, and secret drift.

For your Agent
Project health check

Read-only audit across services, environments, and secret drift.

How it works

The MCP server is a thin wrapper around the existing CLI. Each tool spawns npx tsdevstack <command> as a child process and captures the output. There are no direct imports from other CLI packages. The MCP server is a standalone wrapper.

  • Transport: stdio (the AI client spawns the server as a child process)
  • No background process: The server starts when the client connects and exits when it disconnects
  • Same permissions: The MCP server runs with your local credentials, same as running CLI commands manually

Tools

The server exposes 57 tools organized into query tools (read-only) and action tools (mutating).

Query tools (14)

Read-only operations. Two of them read sensitive data, get_logs and get_secret, so the agent asks you before each call (see Safety model).

ToolDescription
list_servicesList all services with their types, ports, and dependencies
list_environmentsList configured cloud environments and their providers
get_project_configFull project configuration
get_infrastructure_configPer-environment settings: DB tiers, domains, scaling
get_service_statusCloud resource status for a specific service
list_deployed_servicesAll deployed services in a cloud environment
list_secretsSecret names in a cloud environment (no values)
diff_secretsCompare local vs cloud secrets
get_secretGet a single secret value from cloud. The agent asks you first
list_schedulersScheduled jobs and their status
plan_db_migratePreview pending database migrations
infra_planTerraform plan: preview infrastructure changes
infra_statusCheck if infrastructure config is in sync
get_logsNewest log lines of a deployed environment, or its log sources. The agent asks you first

Action tools: local (14)

Low-risk operations that modify local files only.

ToolDescription
syncRegenerate all local config (secrets, docker-compose, kong, migrations)
generate_secretsRegenerate local secrets files
generate_kongRegenerate Kong gateway config from OpenAPI specs
generate_docker_composeRegenerate docker-compose.yml
add_serviceAdd a new service (nestjs, nextjs, or spa)
remove_serviceRemove a service from the local project
generate_clientGenerate TypeScript HTTP client from a service's OpenAPI spec
add_bucket_storageAdd an object storage bucket
remove_bucket_storageRemove an object storage bucket
register_detached_workerRegister a detached worker in config
unregister_detached_workerRemove a detached worker from config
add_messaging_topicAdd a messaging topic to config
remove_messaging_topicRemove a messaging topic from config
update_messaging_topicUpdate publishers/subscribers for a topic

Action tools: cloud (16)

Higher-risk operations that modify cloud infrastructure.

ToolDestructiveDescription
cloud_secrets_pushNoPush framework secrets to cloud without prompts; lists user secrets still missing
cloud_secrets_setNoSet a single secret in cloud
cloud_secrets_removeYesRemove a secret from cloud
cloud_secrets_migrateNoCopy secrets an older CLI left in old places to where the services read them
cloud_secrets_cleanupYesDelete the old copies of moved secrets (after the deploy)
infra_deployNoFull deployment (Terraform + build + deploy all)
deploy_servicesNoDeploy code changes to existing services
deploy_serviceNoBuild, push, and deploy a single service
deploy_kongNoRebuild and deploy Kong gateway
deploy_lbNoDeploy/update the load balancer
run_db_migrateNoApply pending database migrations
deploy_schedulersNoDeploy all scheduled jobs
deploy_schedulerNoDeploy a single scheduled job
remove_service_cloudYesRemove a service from cloud (permanent)
remove_detached_workerYesRemove a worker from cloud (permanent)
infra_destroyYesDestroy ALL cloud infrastructure for an environment

Action tools: setup and CI (13)

Infrastructure setup, Docker builds, and CI/CD operations.

ToolDescription
cloud_initInitialize cloud provider credentials
infra_bootstrapBootstrap cloud project (enable APIs, add roles)
infra_initInitialize infrastructure (Terraform state bucket)
infra_generateGenerate Terraform files from config
infra_generate_dockerGenerate Dockerfiles for services
infra_build_dockerBuild Docker images
infra_push_dockerPush Docker images to registry
infra_generate_kongGenerate Kong declarative config from OpenAPI specs
infra_build_kongBuild Kong Docker image
infra_init_ciInitialize CI/CD workflows
infra_generate_ciRegenerate CI workflows
remove_schedulerRemove a scheduled job from cloud
validate_serviceValidate service naming conventions and structure

Resources

The server exposes 12 resources that provide project context to AI agents.

Project state (dynamic)

These read files from your project and stay up-to-date:

URIDescription
tsdevstack://config.tsdevstack/config.json: service definitions
tsdevstack://infrastructure.tsdevstack/infrastructure.json: per-environment settings
tsdevstack://infrastructure-schema.tsdevstack/infrastructure.schema.json: JSON schema
tsdevstack://ci.tsdevstack/ci.json: CI/CD configuration
tsdevstack://secrets/map.tsdevstack/secret-map.json: secret structure
tsdevstack://secrets/names.secrets.local.json: local secret names and scopes (every value hidden)
tsdevstack://secrets/user.secrets.user.json: user-defined secrets (keys only, every value hidden)
tsdevstack://kong/routeskong.tsdevstack.yml: API gateway routes

Guides (static)

Hardcoded reference content for AI agents:

URIDescription
tsdevstack://guideCore concepts and anti-patterns
tsdevstack://guide/workflowsStep-by-step workflow chains
tsdevstack://guide/nest-commonnest-common library reference
tsdevstack://guide/configConfig files reference

Safety model

The MCP server uses tool annotations to communicate risk to AI clients:

  • readOnlyHint: true: Query tools. They change nothing.
  • Sensitive reads: logs can hold personal data, and get_secret returns a secret's value. The server's instructions and the descriptions of get_logs and get_secret tell the agent to ask you before every call, say what it wants to read and why, and wait for your yes. MCP has no way to enforce this: your AI client decides how it uses the tools. The secrets resources show key names only.
  • destructiveHint: true: Tools that permanently delete data (remove_service_cloud, infra_destroy, etc.). AI clients should always confirm before running these.
  • idempotentHint: true: Tools that can be safely re-run (most generate/deploy commands).

Long-running commands like infra_deploy (30+ minutes) include a note in their description advising the AI to suggest the user runs them in their terminal instead.

Client configuration

Claude Code / VS Code

Add .mcp.json to your project root (shown above in Quick start). Claude Code picks it up automatically.

Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "tsdevstack": {
      "command": "npx",
      "args": ["tsdevstack", "mcp:serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor

Cursor supports MCP servers via its settings. Add the same command configuration in Cursor's MCP server settings.