> ## Documentation Index
> Fetch the complete documentation index at: https://docs.specode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Specode MCP

> Connect Specode's HIPAA tooling to Codex, Claude Code, or Cursor and build, scan, and fix healthcare apps from your own agent.

The Specode MCP connects Specode's HIPAA tooling to the AI coding agent you already use - Codex, Claude Code, or Cursor. You talk to your agent the way you normally would. The agent calls Specode to start a HIPAA-ready app, add a compliant backend to an existing frontend, or scan an app and fix what the scan finds.

## Before You Start

> [!NOTE]
>
> The MCP does not deploy your app. See [Going to Production](#going-to-production) below.

**Current limitations:**

* **Supported agents:** Codex, Claude Code, and Cursor. Lovable and Replit are not supported yet - support for both is coming soon.
* **External projects are read-only in Specode.** A project you create through the MCP appears in your Specode dashboard as an external project. You can see its scans and score there, but you can't open or edit it in the Specode builder yet.
* **Scanner languages:** The scanner reads TypeScript, JavaScript, and SQL only. It does not scan Python, Go, Ruby, PHP, or other backend languages.
* **Best results on tested stacks.** React + TypeScript frontends get the most complete coverage. Backends: Convex, Supabase, and Node.js with Postgres are all supported. Apps on other stacks still scan, but results may be less complete, especially for non-React frontends.
* **Non-template apps:** Some non-template apps may have incomplete dependency detection, and some frontend files and database schemas may not be fully covered.
* **Scans take time.** A first full scan takes 10-50 minutes and runs on Specode's servers, so your agent can keep working while you wait. Rechecks of individual issues are faster.

## Setup

You need a Specode account. Each agent asks you to sign in to Specode the first time it connects.

**MCP server URL:** `https://app.specode.ai/mcp`

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add specode --url https://app.specode.ai/mcp
> codex mcp login specode
> ```
>
> Or add it to `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.specode]
> url = "https://app.specode.ai/mcp"
> ```
>
> > [!WARNING]
> >
> > **Allow network access.** Codex sandboxes network access by default, so `codex mcp login specode` can fail during sign-in. Add this to `~/.codex/config.toml`, then run Codex interactively and sign in again:
> >
> > ```toml theme={null}
> > [sandbox_workspace_write]
> > network_access = true
> > ```

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http specode https://app.specode.ai/mcp
> ```
>
> Then run `/mcp` inside Claude Code, select **specode**, and sign in.

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "specode": { "url": "https://app.specode.ai/mcp" }
>   }
> }
> ```
>
> Then open **Settings → MCP**, check that **specode** is enabled, and sign in when prompted.

**Check the connection:** Ask your agent "What can the Specode MCP do?" It should list the available Specode tools.

## What You Can Do

> [accordion] Start a HIPAA-ready app from scratch
>
> Open an empty folder and describe what you want to build. Specode sets up its stack - React + TypeScript + Convex, with authentication, audit logging, and HIPAA guardrails already in place. Your agent then builds the app on top of that stack.
>
> ```text theme={null}
> Build a HIPAA-compliant patient intake app using Specode.
> Practices enter patients, staff review submissions, and admins see reports.
> ```

> [accordion] Add a backend to a frontend you already have
>
> If you have a React + Vite UI with no backend - for example a prototype from a design tool or an AI app builder - Specode can add a Convex backend with auth and PHI handling, and your agent connects the UI to it.
>
> ```text theme={null}
> This is a frontend-only app. Use Specode to add a HIPAA-ready backend
> and connect the forms to it.
> ```
>
> If your app already has a different backend, your agent explains your options before making changes. Auto-migration is not supported - you'll get a migration notice with next steps.

> [accordion] Scan any app for HIPAA issues
>
> Open the project in your agent and ask for a scan. This works for apps built on the Specode stack and for apps built without it (see stack limitations above).
>
> ```text theme={null}
> Connect this project to Specode and run a HIPAA scan.
> ```
>
> ```text theme={null}
> Is the scan done yet?
> ```
>
> ```text theme={null}
> What's my HIPAA score?
> ```
>
> You get a score and a list of issues, sorted into must-fix and nice-to-fix, grouped by category (access control, audit logging, file handling, sessions, browser storage, etc.).
>
> **How scanning works:** Your agent packages the project as a zip and uploads it to Specode. The scan runs on that snapshot. After fixes, the agent uploads a fresh snapshot before rechecking.

> [accordion] Fix, recheck, and dismiss issues
>
> You don't need to run a full scan after every fix:
>
> ```text theme={null}
> List the remaining issues.
> ```
>
> ```text theme={null}
> Fix the must-fix issues.
> ```
>
> ```text theme={null}
> Explain issue X and fix it.
> ```
>
> ```text theme={null}
> Recheck the issues you just fixed.
> ```
>
> Your agent pulls the fix details from Specode, edits your code, and asks Specode to recheck only those issues. A recheck reports each issue as fixed or still present. If a fix didn't hold, the agent tries again.
>
> If an issue doesn't apply to your app, you can dismiss it with a reason and restore it later:
>
> ```text theme={null}
> Dismiss the analytics issue. We don't load any third-party scripts on pages with PHI.
> ```
>
> ```text theme={null}
> Restore the issue I dismissed.
> ```
>
> Agents only dismiss an issue when you ask them to.

> [accordion] Get HIPAA guidance while you build
>
> Before your agent touches sensitive areas, it can ask Specode for guidance. Sensitive areas include logging, auth, file uploads, browser storage, URLs, email/SMS, and analytics. You can also ask directly:
>
> ```text theme={null}
> What's the HIPAA-safe way to handle file uploads in this app?
> ```

## Going to Production

The Specode MCP builds, scans, and fixes your app. It does not deploy it. The Convex backend created through the MCP is a Specode development deployment - it is not under your BAA and is not suitable for production use with real PHI.

When you're ready to go live:

**1. Set up your own hosting under a BAA**

Move the app to a hosting account you control, where you have a Business Associate Agreement with every vendor that stores or processes PHI. For the Specode stack, that means your own Convex account (with a BAA) and a production deployment with fresh secrets.

**2. Generate new secrets**

Don't reuse development data or auth secrets.

**3. Run a final full scan**

Scan the exact code you're shipping.

**4. Sign BAAs with all third-party services**

Any service that stores or processes PHI needs a BAA in place.

If you want to deploy directly through the Specode platform instead, see [Going Live](https://docs.specode.ai/overview/configuration-deployment/going-live.md). For help with either path, reach out to [support@specode.ai](mailto:support@specode.ai).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.