Coaade MCP / Docs

Coaade MCP docs

Connect any MCP client to your Coaade account: setup, API keys, every tool, limits and errors.

Overview

Coaade MCP is a remote Model Context Protocol server for your whole Coaade account. An AI tool connected to it can work on your projects the way Coaade's own AI does in the IDE: read and change files in the project's cloud Linux workspace, run commands, deploy, manage databases, use GitHub, run App Test, and more.

  • Server: https://api.coaade.com/mcp, Streamable HTTP, stateless.
  • Sign-in: a Coaade API key in the Authorization header.
  • Plans: connecting works on every plan, including Free, and your plan's limits apply. A few tools need a paid plan (Pro and up) and are marked paid below: run_app_test, security_scan, pen_test and the Copilot CTO tools.
  • AI: your tool's own subscription does the thinking. Only ask_coaade, run_app_test and pen_test use Coaade's AI allowance.

Setup

Most tools only need the URL: they send you to coaade.com to sign in and approve. Tools that take a custom header can use an API key instead: create one in Coaade Cloud IDE → MCP (it's shown once) and replace coaade_sk_YOUR_KEY with it.

ChatGPT

On ChatGPT web (plans with developer mode or custom connectors): Settings → Apps & Connectors → Create. Choose OAuth; ChatGPT opens coaade.com, where you sign in and press Allow. (Newer ChatGPT versions put this under Plugins → Add custom MCP server.)

Name:            Coaade
MCP server URL:  https://api.coaade.com/mcp
Authentication:  OAuth

Claude (claude.ai and Claude Desktop)

Settings → Connectors → Add custom connector. Claude opens coaade.com to sign in and approve.

Name:  Coaade
URL:   https://api.coaade.com/mcp

Claude Code

Run in your terminal, then type /mcp in Claude Code and choose Coaade to sign in. Add --scope user to use it in every project. To use an API key instead, add the header.

claude mcp add --transport http coaade https://api.coaade.com/mcp

# or with an API key:
claude mcp add --transport http coaade https://api.coaade.com/mcp \
  --header "Authorization: Bearer coaade_sk_YOUR_KEY"

Kiro

~/.kiro/settings/mcp.json (all workspaces) or .kiro/settings/mcp.json (one workspace), then enable it in the MCP Servers panel. Kiro connects to the remote server over this URL, so use a recent Kiro version. Prefer no key? Remove the headers line and Kiro opens coaade.com to sign in.

{
  "mcpServers": {
    "coaade": {
      "url": "https://api.coaade.com/mcp",
      "headers": {
        "Authorization": "Bearer coaade_sk_YOUR_KEY"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then turn it on under Customize. Cursor connects over this URL, so use a recent version. Prefer no key? Remove the headers line and Cursor opens coaade.com to sign in.

{
  "mcpServers": {
    "coaade": {
      "url": "https://api.coaade.com/mcp",
      "headers": {
        "Authorization": "Bearer coaade_sk_YOUR_KEY"
      }
    }
  }
}

VS Code

.vscode/mcp.json, or “MCP: Open User Configuration” from the command palette, then Start the server. Note the servers key and type: http. Prefer no key? Remove the headers line and VS Code opens coaade.com to sign in.

{
  "servers": {
    "coaade": {
      "type": "http",
      "url": "https://api.coaade.com/mcp",
      "headers": {
        "Authorization": "Bearer coaade_sk_YOUR_KEY"
      }
    }
  }
}

Claude Desktop with an API key

If you'd rather use an API key than the connector above: Settings → Developer → Edit Config (claude_desktop_config.json). This uses the mcp-remote bridge (needs Node.js). Restart Claude Desktop after saving.

{
  "mcpServers": {
    "coaade": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.coaade.com/mcp",
        "--header",
        "Authorization:${COAADE_AUTH}"
      ],
      "env": {
        "COAADE_AUTH": "Bearer coaade_sk_YOUR_KEY"
      }
    }
  }
}

Other clients

Any client that supports remote MCP servers over Streamable HTTP, with MCP OAuth sign-in or a custom header.

URL:       https://api.coaade.com/mcp
Transport: Streamable HTTP (POST)
Sign-in:   OAuth 2.1 (discovered from the 401), or
Header:    Authorization: Bearer coaade_sk_YOUR_KEY

Keep the key out of shared repositories: put it in your tool's user-level config, or in an environment variable if your tool supports variables in headers (check its docs for the exact syntax).

Fewer tools

Some clients cap how many tools they take. Add ?groups= to the URL to offer only some groups, for example https://api.coaade.com/mcp?groups=projects,files,deploy. Groups: projects, files, deploy, databases, github, apptest, security, agent, memory, schedules, cto, account.

Sign-in and access

Sign in with Coaade (OAuth). Like connecting a plugin. When your tool first calls the server, it learns how to sign in and sends you to coaade.com. There you sign in, see which app is asking and where it returns, choose full access or read only, and press Allow. The app gets its own token for Coaade MCP (never your password), which it refreshes on its own. Each approved app is listed in Coaade Cloud IDE → MCP, where you can disconnect it; that stops it at once.

API keys. For tools that take a header, every request carries Authorization: Bearer coaade_sk_….

Either way, the connection acts as you: your projects, your plan, and your role on projects others shared with you.

  • Full access keys see every tool.
  • Read only (a key, or an app you approved as read only) sees only the tools marked read below, and run_sql only runs SELECT-style queries.
  • On a project shared with you as a viewer, every key is read-only for that project.
  • Keys and tokens are stored hashed. Keys are shown once. Revoke a key or disconnect an app in the IDE's MCP page and it stops working at once.
  • How many keys you can have depends on your plan (see pricing).

Using the tools

  • Start with list_projects, then get_project for the one you work on.
  • Every project tool takes project, the slug. A project shared with you also needs owner, the owner id that list_projects shows.
  • read_file returns numbered lines and reads large files in parts with start_line / end_line. Leave the numbers out of edit_file's old_text.
  • edit_file must match exactly one place, unless you set replace_all.
  • Changes are saved to the project a few seconds after the last edit, so they open in the IDE. Refresh an IDE tab that already has the project open.
  • run_app_test and ask_coaade run in the background for minutes: they return an id right away. Read the result with get_test_run or get_session.
  • Planning documents (specs, plans) belong in the project's .coaade/ folder, which is never deployed.

Tool reference

57 tools. read tools work with read-only keys; write tools need a full-access key; destructive tools can't be undone and are marked so your client asks you first. The role is what you need on the project. A paid tag means the tool needs a paid plan (Pro and up) — on Free it returns a plan error; the other 50 tools work on every plan.

Projects (projects)

ToolDoesInputsAccessRole
list_projectsList the Coaade projects you can use: your own and ones shared with you (with their owner id, which shared projects need as `owner` in other tools).—read—
get_projectA project's live state on Coaade: your role, its deploy (URL, last deploy), databases, GitHub link, scheduled tasks, Copilot CTO and App Test.—readviewer
create_projectCreate a new Coaade project, optionally from a template.name, template?write—
rename_projectRename a project you own (its slug changes too).new_namewriteowner

Files and terminal (files)

ToolDoesInputsAccessRole
list_filesList files and folders in the project or a directory (4 levels deep).directoryreadviewer
read_fileRead a project file, with line numbers (number, tab, line).path, start_line?, end_line?readviewer
search_filesSearch the project files (grep): matching lines with file paths and line numbers.query, regex?, path?, ignore_case?, max_results?readviewer
write_fileCreate a file or replace a whole file in the project (complete content).path, contentwriteeditor
edit_fileReplace exact text in a file.path, old_text, new_text, replace_all?writeeditor
delete_fileDelete a file from the project.pathdestructiveeditor
rename_fileRename or move a file within the project.old_path, new_pathwriteeditor
run_commandRun a shell command in the project's cloud workspace and return its output and exit code.command, background?writeeditor
task_outputLatest output of a background task started with run_terminal (background: true), and whether it is still running.task_idreadviewer
task_stopStop a background task and everything it started.task_idwriteeditor

Deploy (deploy)

ToolDoesInputsAccessRole
deployDeploy this project to <name>.coaade.app, or publish the latest changes if it is already deployed (the workspace is saved first).—writeeditor
deploy_logsThe latest deployment's log, and for a server app its state (running, crashed, restarts) and its recent output and errors.—readviewer
deploy_set_envSet environment variables of the deployed server app (replaces the whole set) and restart it.varswriteeditor
stop_deployTake the project's deployed site offline (redeploy with deploy to bring it back).—destructiveowner
list_domainsThe project's custom domains and whether each is verified (domains are added in the IDE's Deploy dialog).—readowner

Databases (databases)

ToolDoesInputsAccessRole
db_listThis project's databases (type, name, size limit, status, id) and what the plan allows.—readviewer
db_createCreate a database for this project, within the user's plan (PostgreSQL, MongoDB or Redis).typewriteeditor
db_connectionA database's connection URL and credentials.db_idreadeditor
db_sizeHow much of its size limit a database uses.db_idreadviewer
db_deleteDelete one of this project's databases and all its data.db_iddestructiveowner
run_sqlRun SQL on one of the project's PostgreSQL databases (the same rules as the IDE's Database tab: viewers read only).db_id, sqlreadviewer

GitHub (github)

ToolDoesInputsAccessRole
github_statusThe user's GitHub connection (account, repository access) and this project's git state: linked repository (origin), current branch, uncommitted changes, recent commits.—readviewer
github_reposRepositories the user gave Coaade access to (owner/name, private, default branch).—readviewer
github_activityWhat happened on GitHub since this project last pushed or pulled: new commits on the linked branch, who pushed, open pull requests.—readviewer
github_link_repoPoint this project's git remote (origin) at one of the user's repositories.repowriteeditor
github_pushPush this project to its linked GitHub repository.commit_message?, branch?writeeditor
github_pullPull the linked GitHub repository's branch into this project (merges; stops on conflicts and reports them).branch?writeeditor

App Test (apptest)

ToolDoesInputsAccessRole
run_app_testpaidStart App Test: an AI tester uses the project's DEPLOYED site in a real cloud browser like a first-time user (plans, uses made-up data, checks desktop and mobile, watches console and network errors).goal, url?writeeditor
list_test_runsThe project's recent App Test runs: goal, status, verdict and when.—readviewer
get_test_runOne App Test run: status (running/done/stopped/error), verdict, each check, the bugs with steps to reproduce, the page's errors and optionally the Playwright spec.run_id, include_spec?readviewer

Security scan (security)

ToolDoesInputsAccessRole
security_scanpaidRun a lightweight, non-destructive security scan (pen test) of the project's own DEPLOYED site: security headers (CSP, HSTS, clickjacking, nosniff, referrer), cookie flags (Secure, HttpOnly, SameSite), http→https redirect, permissive CORS, software-version disclosure, and accidentally published secrets (.env, .git, credentials). It only ever scans this project's own site, sends no attack payloads and changes nothing. Returns findings with severity and how to fix each.url?readviewer
list_security_scansThe project's recent security scans: target, a one-line summary and when.—readviewer
get_security_scanOne security scan: its target and every finding, each with severity and how to fix it.scan_idreadviewer
pen_testpaidStart an AI pen test & QA pass: an agent drives the project's own DEPLOYED site in a real AWS cloud browser and sends crafted (safe, non-destructive) HTTP requests to it, hunting the issues a penetration tester and QA engineer look for — authentication, access control, injection, data exposure, transport and broken flows. It only ever tests this project's own site. Returns a run id; read the score and findings with get_pentest_run.goal?, url?writeeditor
list_pentest_runsThe project's recent AI pen test runs: target, status, security score and when.—readviewer
get_pentest_runOne AI pen test run: status, security score, verdict, and every finding with severity, category, evidence and how to fix it.run_idreadviewer

Coaade Code (agent)

ToolDoesInputsAccessRole
ask_coaadeHand a task to Coaade Code, Coaade's own AI engineer, which works on the project's workspace with every Coaade tool.task, session_id?, autonomous?writeeditor
get_sessionA Coaade Code (AI Chat) session: whether it is still working, and its latest messages.session_id, last?readviewer
list_sessionsYour saved Coaade Code (AI Chat) sessions in a project, newest first.—readviewer

Project memory (memory)

ToolDoesInputsAccessRole
memory_listThe project's memory: short notes (preferences, conventions, decisions) Coaade's AI reads before it works.query?readviewer
memory_addSave a durable note to the project's memory (a preference, convention or decision) that Coaade's AI and future sessions will follow.note, remove?writeeditor
memory_searchSearch this project's saved notes (project memory), including older ones not shown above.queryreadviewer

Scheduled tasks (schedules)

ToolDoesInputsAccessRole
schedule_listThis project's scheduled tasks: id, name, AI task or command, when it runs (in the user's timezone), next run, last result, paused or not.—readviewer
schedule_createSchedule a task to run automatically at set times on the server, without the IDE open: an AI task (a prompt you will carry out on your own each time; your final message is the report) or a shell command.name, kind, prompt?, command?, schedule, notify?writeeditor
schedule_updateChange a scheduled task: its time, instructions, command, name or emails, or pause (enabled false) / resume (enabled true) it.id, name?, prompt?, command?, schedule?, notify?, enabled?writeeditor
schedule_run_nowRun a scheduled task right away, in the background (to try it out).idwriteeditor
schedule_deleteDelete a scheduled task (and its run history).iddestructiveeditor

Copilot CTO (cto)

ToolDoesInputsAccessRole
cto_proposalspaidCopilot CTO's proposals for the project (bug fixes, improvements, features) with their status.status?readowner
cto_decidepaidApprove or decline a Copilot CTO proposal.id, decision, note?writeowner
cto_reportspaidCopilot CTO's recent runs (daily reviews, tasks) with a short summary of each.—readowner
cto_healthpaidThe deployed app's recent hourly health checks by Copilot CTO (up or down, response time).—readowner

Account (account)

ToolDoesInputsAccessRole
usage_quotaYour Coaade plan and what is used of each quota (AI, projects, storage, builds, databases).—read—
report_bugReport a bug in Coaade (the platform, not the user's own app) to the Coaade team on the user's behalf.summarywrite—

Inputs marked ? are optional. Project tools also take project (required) and owner (shared projects only).

Resources

Clients that read MCP resources get two per project: coaade://project/<slug>/state (deploy, databases, GitHub, schedules, App Test) and coaade://project/<slug>/memory (the project's memory notes). Add ?owner=<id> for a shared project.

Limits and errors

  • 120 requests per minute per key. Over that, the server answers HTTP 429: wait a minute.
  • Your plan's limits apply to what tools do: projects, storage, files, databases, deploys, command time limits and Coaade AI usage.
  • Tool results longer than 100,000 characters are cut; read files in parts instead.
  • A tool that fails returns an error result (isError) with a plain message, for example a missing project, a wrong role, an edit_file match that isn't unique, or a plan limit.
HTTPMeaning
401Not signed in, or an unknown, expired or revoked key or token. The response's WWW-Authenticate header tells the client where to sign in.
405Not a POST. The server is stateless: no GET stream and no sessions to end.
429Too many requests for this key in the last minute.
503Coaade couldn't check the key right now. Try again.

Security

  • Treat an API key like a password. Give each tool its own key so you can revoke one without the others.
  • Prefer a read-only key when the tool only needs to look.
  • db_connection returns database credentials for the project's .env. The server tells AI tools never to put them in code, commits or replies.
  • Each tool call is logged with the key, tool, project and result.
  • Report a problem with report_bug, or write to contact@coaade.com.