Using with Claude Code

Telbase is designed for Claude Code. Every deploy returns structured feedback that Claude reads, interprets, and acts on — no human parsing needed.

Setup

One command registers Telbase as an MCP server and installs the /deploy slash command in Claude Code:

npx telbase mcp register

Deploy this app to Telbase

The /deploy Command

When you type /deploy in Claude Code, it loads a prompt template that teaches Claude how to:

• Check authentication and install the CLI if needed
• Run telbase deploy --local --json --auto
• Read the structured JSON response
• Report the live URL on success
• Auto-fix build failures using the suggestions[] array
• Handle quota limits by explaining the tier and offering the upgrade link

You can also just ask Claude naturally:

Deploy this to Telbase
Deploy this app and set up a PostgreSQL database
Deploy from my GitHub repo https://github.com/user/my-app

MCP Tools

When the MCP server is registered, Claude Code has access to 41 tools it can call directly — without shell commands:

Deploy & Monitoring

• deploy — deploy an app from local files or a GitHub repo. Returns structured JSON with detection context and suggestions.
• get_deploy_status — check if a deploy is building, live, or failed. Useful for polling after a --no-wait deploy.
• get_deploy_logs — fetch build or runtime logs for a specific deployment.
• list_deploys — list recent deploys with status, trigger, timestamps, and commit info. Find deploy IDs for rollback or log inspection.
• cancel_deploy — cancel an in-progress deploy (building or pending).
• get_app_logs — get live application logs (runtime, not build). Use after health check fails to diagnose crashes.

Project Management

• list_projects — list all projects with status, URL, provider, and database info.
• get_project — get detailed project info including framework, services, domains, GitHub link, and warm start status.
• update_project — update project settings (name, slug, description, pre-deploy command).
• delete_project — permanently delete a project and all resources. Always confirm with user first.

Service Control

• check_app_health — check if a deployed app is healthy by probing its URL.
• restart_service — gracefully restart a running service without redeploying. First response for unhealthy apps.
• reset_service — delete and recreate a broken provider resource. Recovery tool for stuck revisions.
• suspend_service — pause a service (stops traffic, returns 402). For cost management or maintenance.
• resume_service — resume a suspended service. Restores warm start if previously enabled.

Rollback

• rollback_deploy — instantly rollback to a previous working deploy (~30 seconds to restore).
• list_rollback_targets — list available rollback targets (recent successful deploys).

Environment Variables

• set_env_vars — set environment variables on a project. Persists across deploys. Encrypted at rest.
• list_env_vars — list environment variables (values masked). Diagnose missing vars before deploy.
• delete_env_var — delete an environment variable. Auto-applied to running services.

Database

• get_database_info — get database status, provider (Neon/Turso/Cloud SQL), extensions, and tier.
• enable_database_extension — enable pgvector, PostGIS, pg_trgm, or uuid-ossp. Supports embedding dimension presets.

Custom Domains

• add_custom_domain — add a custom domain to a deployed project. Returns DNS instructions with detected registrar.
• verify_custom_domain — verify DNS configuration and activate SSL.
• list_custom_domains — list all custom domains with verification and SSL status.
• remove_custom_domain — remove a custom domain from a project.

Scheduled Jobs

• get_job_executions — list execution history with status, timestamps, and duration.
• run_scheduled_job — manually trigger a scheduled job outside its cron schedule.
• pause_job — pause a scheduled job's cron schedule. The job remains deployed but won't execute until resumed.
• resume_job — resume a paused scheduled job. Restores the cron schedule.
• update_schedule — update the cron expression or timezone without redeploying.

Storage

• get_storage_info — get file storage (R2) bucket status, CORS origins, and config.
• get_storage_credentials — get S3-compatible credentials for code (accessKeyId, secretAccessKey, endpoint).

GitHub

• get_github_status — check if a GitHub repo is connected and auto-deploy settings.
• connect_github — link a GitHub repository for auto-deploy on push.
• toggle_auto_deploy — enable or disable automatic deploys on push.

Team & Organization

• list_team — list team members with email, role, and join date.
• invite_member — invite a new team member (admin, developer, or viewer).
• list_orgs — list all organizations you belong to.
• switch_org — switch the active organization context.

Account

• get_account_status — get plan tier, deploy usage, credit balance, quotas, and auto-refill settings.

Documentation Resources

The MCP server exposes 14 documentation resources that Claude reads for context when making decisions. Each is available at telbase://docs/{topic}:

• frameworks — detection rules, provider routing, database support, plan requirements
• rag — pgvector setup, embedding presets, environment variables, monorepo patterns
• custom-domains — per-project domains, DNS setup, verification, SSL
• billing — plan pricing, credits, auto-refill, deploy response billing data
• debugging — error code reference, self-healing recipes, retriable errors
• multi-service — monorepo patterns, service dependencies, env var scoping
• env-vars — auto-injected vars by provider, precedence rules, common issues
• github — auto-deploy on push, preview environments, root directory, commit status
• scheduled-jobs — cron scheduling, slot pricing, execution history, circuit breaker
• storage — S3-compatible file storage, CORS, credentials, SDK examples
• database — provider selection (Neon/Turso/Cloud SQL), connection strings, migrations
• access-control — Cloudflare Access, email OTP, domain/email allowlists
• warm-start — eliminate cold starts on GCP, pricing, eligibility, billing
• rollback — rollback workflow, targets, database caveats, self-healing loop

Guided Prompts

Three built-in prompts provide step-by-step workflows for common operations:

• debug-deploy-failure — systematic workflow to diagnose and fix a failed deploy. Guides through error analysis, log reading, and recovery (rollback or fix-and-redeploy).
• project-health-check — comprehensive health assessment of a deployed project. Checks app status, logs, database, env vars, and recent deploys.
• capacity-planning — assess current resource usage, forecast constraints, and recommend plan tier upgrades or credit purchases.

The AI Feedback Loop

This is what makes Telbase different from other platforms. Every deploy response includes machine-actionable structured feedback. When a build fails, Claude reads the AI-powered diagnosis — including root cause, confidence score, and auto-fixable code changes:

{
  "data": {
    "status": "failed",
    "errorCode": "BUILD_FAILED",
    "extractedErrors": [
      {
        "code": "MISSING_DEPENDENCY",
        "title": "Missing @prisma/client",
        "suggestion": "npm install @prisma/client"
      }
    ],
    "suggestions": [
      {
        "type": "code_change",
        "detail": "Add @prisma/client to dependencies in package.json"
      },
      {
        "type": "cli_retry",
        "command": "telbase deploy --local --json --auto"
      }
    ],
    "detection": {
      "ormType": "prisma",
      "ormConfidence": 0.95,
      "databaseProvider": "neon",
      "warnings": []
    },
    "aiDiagnosis": {
      "diagnosis": "prisma is in devDependencies but needed at build time",
      "confidence": 0.92,
      "category": "missing_dependency",
      "fixes": [{ "type": "dependency", "description": "Move @prisma/client to dependencies", "autoFixable": true }],
      "fixesAreAlternatives": false
    }
  }
}

The self-healing loop works like this:

1. Deploy — Claude runs telbase deploy --json --auto
2. Read feedback — Claude reads aiDiagnosis (when present, confidence ≥ 0.7) or falls back to extractedErrors and suggestions[]
3. Fix — Claude applies fixes where autoFixable: true (install deps, fix imports, update config)
4. Redeploy — Claude runs the cli_retry command or uses redeployCommand from the diagnosis
5. Success — Claude reports the live URL to you

Suggestion types

• cli_retry — a CLI command to run (e.g., redeploy with different flags)
• code_change — a code modification to make (e.g., install a dependency, fix an import)
• user_action — something that requires human intervention (e.g., add a DNS record, upgrade plan)

Prompt Examples

Copy these prompts to get started quickly:

Deploy a new app

Build me a project tracker with a PostgreSQL database using Next.js and Prisma, then deploy it to Telbase.

Deploy an existing project

Deploy this project to Telbase. If the build fails, read the error suggestions and fix the code.

Add a database to an existing app

Add a SQLite database to this app using Prisma, create a schema for tracking approvals, then redeploy to Telbase.

Set environment variables and deploy

Set these environment variables on my Telbase project and redeploy:
- OPENAI_API_KEY=sk-...
- RESEND_API_KEY=re_...

Debug a failed deploy

My last deploy to Telbase failed. Check the build logs, figure out what went wrong, fix it, and redeploy.

Deploy from GitHub

Deploy https://github.com/myorg/internal-dashboard to Telbase and set up auto-deploy on push.

Add a custom domain

Set up app.acme.com as a custom domain on my Telbase project and verify the DNS.

Deploy a Docker container

Deploy this Java Spring Boot app to Telbase using the existing Dockerfile. Docker support is available on all paid plans.

Deploy a scheduled job

Deploy this data pipeline as a scheduled job that runs every hour at the top of the hour, Eastern time.

Per-Project Setup

For project-specific MCP configuration, Telbase creates a .telbase/mcp.json file in your project directory. This is useful when you want Claude Code to automatically discover the Telbase tools when working in a specific project:

# Install project-level MCP config
npx telbase mcp register

The project config is added to .gitignore automatically.

Next Steps

• Quick Start — deploy your first app
• Databases — auto-provisioning, migrations, and pgvector
• CLI Reference — every command and flag
• Guides & Articles — tips and patterns for deploying with Claude Code