# Quickstart with MCP

> Connect your agent to Nevia over MCP, create a Postgres database, and branch it to test changes

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/get-started/mcp

This quickstart runs the same exercise as the [Quickstart](https://nevia.cloud/docs/get-started/quickstart.md),
but your coding agent does the work. It connects over MCP, creates a Postgres
database and branches it. The branch is a copy of your data you can change
while the original keeps running.

## Prerequisites

You need:

* A coding agent that supports MCP and can run local terminal commands, such as
  Claude Code, Codex or Cursor.
* A browser for sign-in.
* The `psql` Postgres client, installed where your agent runs terminal commands.
* A Nevia workspace where you have the **admin** or **editor** role. Nevia
  creates a `default` workspace the first time you sign in, so a new account
  already qualifies.

The agent manages databases with Nevia's MCP tools and runs SQL with `psql`. You
don't need the Nevia CLI.

If `psql` is missing, install it:

```bash
# macOS
brew install libpq && brew link --force libpq

# Debian / Ubuntu
sudo apt install postgresql-client
```

Check the install:

```bash
psql --version
```

This prints the Postgres client version.

## 1. Add the server

Claude Code and Codex take one command. Cursor takes
[one click](cursor://anysphere.cursor-deeplink/mcp/install?name=nevia\&config=eyJ1cmwiOiJodHRwczovL2FwaS5uZXZpYS5jbG91ZC9tY3AifQ==).
Any other client that supports [Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports/streamable-http)
needs only the server URL:

**Claude Code**

```bash
claude mcp add --transport http nevia https://api.nevia.cloud/mcp
```

**Codex**

```bash
codex mcp add nevia --url https://api.nevia.cloud/mcp
```

**Other clients**

```json
{
  "mcpServers": {
    "nevia": {
      "url": "https://api.nevia.cloud/mcp"
    }
  }
}
```

Then sign in. In Claude Code, run `/mcp` and pick `nevia` to open your browser.
In Codex, run `codex mcp login nevia`. Cursor and most other clients show a
sign-in button next to the server. The tools appear after you sign in. If they
don't, restart or reconnect the client.

Use the URL without `?readonly=true`. This exercise needs write tools.

## 2. Select a workspace

Ask your agent:

```text
Using the Nevia MCP tools, show my workspaces and my role in each.
```

The agent lists your identity and workspace IDs. Pick a workspace where you are
**admin** or **editor**; `default` works. Then give the agent its full ID:

```text
Use workspace 01d4cnjjq40hnnh0nwmkg35nv2h for this exercise. Check that the database names orders
and orders-staging are available. If either name is taken, stop and tell me.
```

Replace `01d4cnjjq40hnnh0nwmkg35nv2h` with your workspace ID. If the agent reports
a taken name, ask it to delete that database or choose another name.
The [database tools](https://nevia.cloud/docs/reference/mcp.md#databases) reference lists the tools
the agent uses.

## 3. Create a database

Version, size and storage take platform defaults, so the agent needs only a
name:

```text
In the selected workspace, create a Postgres database named orders with the
defaults. Show its name, ID and state. Leave credentials out of your summary.
```

The result shows `orders`, an ID and state `ready`, with no pending
transition. If an operation is still in progress, the agent should follow the
tool's `next_steps` and track the existing operation instead of repeating the
create call. See [Waiting](https://nevia.cloud/docs/reference/mcp.md#waiting) in the Remote MCP server
reference.

## 4. Set up a schema and some data

Ask your agent to connect and run SQL:

```text
Get the connection for orders. Use psql in your terminal to run this SQL,
keeping the connection’s sslmode=require or stricter setting. Show the query
result without printing the credentials. Stop if a command fails.

CREATE TABLE IF NOT EXISTS pings (id serial PRIMARY KEY, note text);
INSERT INTO pings (note) VALUES
  ('csv-note-one'), ('csv-note-two'), ('baseline-a'), ('baseline-b');
SELECT count(*) FROM pings;
```

The count is **4**, which also confirms the agent can reach the database. If
connection details are missing or the endpoint is unreachable, see
[Databases](https://nevia.cloud/docs/reference/mcp.md#databases) in the Remote MCP server reference.

## 5. Branch the database

A branch copies the parent's data into a new database with its own connection
string. The source must be ready, with no pending transition or running
operation, and have a persistent data disk supplied by the deployment.

```text
Branch orders as orders-staging. Check that the branch is ready, then get its
connection and use psql to count the rows in pings. Show the count before
making any changes.
```

The branch has **4** rows, and the source keeps running. Now have the agent
change the branch:

```text
Run this SQL against orders-staging only. Show the command results.

INSERT INTO pings (note) VALUES ('branch-mutation');
UPDATE pings SET note = 'baseline-a (edited in branch)' WHERE note = 'baseline-a';
```

The agent reports `INSERT 0 1` and `UPDATE 1`.

## 6. Check the divergence

Ask your agent to compare the two databases:

```text
Run this query against both orders and orders-staging. Label each result with
its database name so I can compare them.

SELECT count(*), array_agg(note ORDER BY id) FROM pings;
```

The source still has **4** rows, and `baseline-a` is unchanged. The branch has
**5** rows, including `branch-mutation` and `baseline-a (edited in branch)`.
Your changes stayed in the branch.

## 7. Clean up

Open the [console](https://console.nevia.cloud/), select the same workspace, and
find `orders` and `orders-staging` under **Databases**.

Delete both databases and their data. Deleting the source leaves its branches
running, so name both:

```text
Show me orders-staging and orders in the selected workspace and ask me to
confirm deletion. Then delete those two databases. List databases by each
name afterward to verify cleanup.
```

After you confirm, each name lookup returns an empty list and neither database
appears in the console.

## Next steps

* [Create and connect to a database](https://nevia.cloud/docs/databases/create.md) covers creation and TLS connections.
* [Branch a database](https://nevia.cloud/docs/databases/branch.md) shows how to copy an existing database.
* [Sleep, wake and delete a database](https://nevia.cloud/docs/databases/lifecycle.md) covers lifecycle actions and protection.
* [Remote MCP server](https://nevia.cloud/docs/reference/mcp.md) lists the tools, access filters and waiting behavior.