---
title: First MCP server
description: Connect Claude to First to build, preview, edit, and publish web apps from a conversation.
---

The First MCP server lets your AI assistant build and publish web apps using your First account.

You can use it to:

- Create an app from a description.
- Follow a build and answer the builder’s questions.
- Request changes and open an available preview.
- Publish a validated app to a public URL.

## Connect your assistant

Use this remote server URL. There is nothing to install on your computer.

```text
https://mcp.first.new/mcp
```

You need a First account. Sign-in uses OAuth with PKCE, so you approve access in your browser without giving the assistant a First password or API key.

### Claude

1. Open **Settings → Connectors** in Claude.
2. Choose **Add custom connector**, name it **First**, and enter the server URL above, including `/mcp`.
3. Complete sign-in to First and review the requested permissions.
4. Start a conversation with First enabled and ask:

```text
Show my First projects.
```

Claude should return the projects your connected account can access. An empty list is expected if you have not created a project yet.

For workspace-managed accounts, your administrator may need to enable custom connectors. See Claude’s [custom connector setup instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Claude Code

Add the remote server from your terminal:

```bash
claude mcp add --transport http first https://mcp.first.new/mcp
```

Open Claude Code, run `/mcp`, select **first**, and complete authentication. Ask it to show your First projects to check the connection.

## Build your first app

Start with a prompt that describes the page and the behavior you want:

```text
Use First to build a workshop website with a schedule, a list of tools to
bring, and venue details. Use sample event details and make it readable
on a phone.
```

The assistant creates a project and checks its progress. If First asks a question, answer it in the conversation. When a preview is available, open it and check the schedule and venue.

To make a change, name the same project and describe the update:

```text
Move the workshop schedule above the tool list. Keep the event details unchanged.
```

When you are ready to share the app, ask the assistant to publish it. Publishing makes the app publicly reachable. Review what you intend to share and confirm the publication request before proceeding. Open the returned URL in a private browser window to verify what visitors can see.

## What permissions do you approve?

First limits the connection to the signed-in account’s accessible projects and the permissions you grant.

| Permission         | What it allows                                                     | Tools                            |
| ------------------ | ------------------------------------------------------------------ | -------------------------------- |
| `projects:read`    | List projects and read build status, questions, previews, and URLs | `list_projects`, `get_project`   |
| `projects:build`   | Create apps, request changes, and answer build questions           | `create_project`, `send_message` |
| `projects:publish` | Publish an app to a public URL                                     | `publish_project`                |

Read-only permission is enough to inspect projects. If a tool needs a permission you did not grant, reconnect and review the requested access.

Disconnect First from your client’s connector settings when you want to stop using the connection.

## Available tools

Your assistant fills in these parameters. Project and build IDs are UUIDs returned by earlier calls.

| Tool              | What it does                                                         | Required parameters                        | Optional parameters                     |
| ----------------- | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------- |
| `create_project`  | Creates an app and starts a build                                    | `name`, `message`, `idempotency_key`       | —                                       |
| `get_project`     | Reads status, pending questions, costs, and available URLs           | `project_id`                               | `turn_id`, `wait_seconds`               |
| `list_projects`   | Lists projects the account can access                                | —                                          | `limit`, `cursor`                       |
| `send_message`    | Requests changes or answers a pending question                       | `project_id`, `message`, `idempotency_key` | `reply_to`, `setup_reply`               |
| `publish_project` | Publishes a validated app or queues publication of a specified build | `project_id`                               | `turn_id`, `when_ready`, `wait_seconds` |

- App names accept **up to 120 characters**. Build and edit messages accept **up to 8,000 characters**.
- `wait_seconds` accepts **1–15 seconds**. The assistant can check again if work is still running.
- `list_projects` accepts a limit of **1–100 projects** per page. Pass its returned cursor to read the next page.
- Each submission needs a new UUID as its `idempotency_key`. Reuse that UUID when retrying the same submission to avoid duplicate work.
- `reply_to` contains the `turn_id` and `question_request_id` for a pending question.
- `setup_reply` contains `turn_id`, `request_id`, and an `action` of `use_saved_configuration` or `decline`. It carries no credentials and cannot be combined with `reply_to`.
- Queued publication uses `when_ready: true` with a `turn_id`. A publication `wait_seconds` also requires `turn_id`. Pending publication has no live URL yet.

An edit can replace or remove existing app content. Clients may ask you to confirm edits and publication before calling those tools.

## Credits and secure setup

Creating an app and sending messages can spend credits from your First account. Reading project lists and build status is free. If credits run out, the account owner needs to review usage and credits in First.

Keep credentials out of prompts. First rejects write messages that it detects contain private keys, API keys, access tokens, or payment card numbers. Configure credentials in First’s editor instead. If a build needs setup, the assistant receives a secure setup URL for you to open in your browser.

Text returned to the assistant is filtered to remove email addresses and credential-like values. Treat your project content as information shared with the client you connected.

## Troubleshooting

| What you see                                              | What it means                                       | What to do                                                            |
| --------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| Sign-in repeats or First appears disconnected             | Authentication has not completed                    | Disconnect and reconnect First, then approve access                   |
| Reconnect with the required project permission            | The tool needs a scope the connection does not have | Reconnect and review the requested permissions                        |
| A message is rejected for containing credentials          | First detected sensitive values in the prompt       | Remove them and configure the service in First                        |
| `TURN_ALREADY_ACTIVE`                                     | The project already has work running                | Ask the assistant to check the project before submitting more changes |
| Wait for a successfully validated build before publishing | The selected build is not ready to publish          | Check build status and resolve any pending questions or errors        |
| Publication address is unavailable                        | The requested address cannot be used                | Open First and choose an available address                            |
| Insufficient credits                                      | The account cannot fund the requested work          | Review credits in First                                               |
| A rate limit or temporary failure                         | The request needs to be retried                     | Retry the same submission with the same idempotency key               |
| A timeout with no clear outcome                           | The build may already have started                  | Check the project before retrying                                     |

If you still need help, email [care@first.new](mailto:care@first.new) with the client name, project ID, and error message. Omit passwords, tokens, and other credentials.

Read First’s [privacy policy](https://first.new/privacy) and [terms](https://first.new/terms) before connecting your account.

## Next steps

- [Preview and iterate](/docs/build/preview-and-iterate). Check your app before sharing it.
- [Publish your app](/docs/publish/publish-your-app). Verify the live version.
