Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

First MCP server

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.

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:
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.

Claude Code

Add the remote server from your terminal:

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:

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:

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 with the client name, project ID, and error message. Omit passwords, tokens, and other credentials.

Read First’s privacy policy and terms before connecting your account.

Next steps

Was this page helpful?