Docs

MCP connector

Give Claude your Buildfyio workspace as tools — hosted, no install.

Add it to Claude

Buildfyio runs a hosted MCP server, so there is nothing to install. In Claude, add a custom connector with this URL:

https://mcp.buildfyio.com/mcp

Claude opens a Buildfyio sign-in, you pick the workspace to grant and approve. It never asks you for a token.

What it can do

Tool	Needs	What it does
list_projects	read	List the projects in the workspace
get_project	read	Settings of one project (branch, commands, analyticsInjection, serverTiming)
list_components	read	The apps of a multi-app project
list_deployments	read	Recent deployments with the app each one belongs to
get_deployment_status	read	Status and URL of a deployment
get_logs	read	Read the archived build, deploy or runtime log
get_build_failure	read	Why a build failed, with a suggested fix
deploy	deploy	Trigger a deployment of the whole project (refuses to report a wrong-env answer as success)
deploy_component	deploy	Deploy one app
rollback	deploy	Roll back to a previous deployment
list_env_vars	env:read	Environment variables of an app (secrets masked unless reveal)
set_env_var	env:write	Create or overwrite an environment variable
list_domains / add_domain / verify_domain	domains	Hostnames and which app each one serves
set_domain_redirect / delete_domain	domains	Apex → www redirects; detach a hostname
create_project	admin	Create a project from a Git repo
update_project	admin	Change settings incl. analyticsInjection and serverTiming
create_component	admin	Add an app: name, rootDir, framework, port, commands, health check
update_component	admin	Change an app (any subset of the same fields, or rename)
delete_component	admin	Remove an app (confirm: true)
list_crons / create_cron / update_cron / delete_cron / list_cron_runs	read / admin	Cron jobs and their runs

Component fields are the API's: name, kind (web | worker | static | cron), framework (docker = the repo's own Dockerfile, unknown = detect at build), rootDir, port, buildCommand, startCommand, outputDir, image, instanceSize, minReplicas, maxReplicas and healthCheck (path, port, intervalSecs, initialDelaySecs, timeoutSecs). There is no dockerfilePath: a Dockerfile at <rootDir>/Dockerfile is used automatically.

Permissions

You choose the scopes when you approve. A tool that needs more than you granted is refused with a message saying so — it does not fail silently or quietly do less.

read — see projects, deployments, logs and build failures.
deploy — trigger deployments and roll back.
env:read / env:write — read and change environment variables.
domains — attach, verify, redirect and detach hostnames.
admin — create projects, change project settings, add / change / remove apps, cron jobs. (update_project and the component tools all need this one; the legacy write scope of older tokens counts as full access.)

Approving creates an API token named Claude (MCP connector). Revoke it under Settings → API tokens; the connector stops working immediately.

Claude Code, Cursor, Windsurf

Editors take the same hosted server with an API token instead of OAuth. The CLI mints a token for the workspace you choose and registers the server — for Claude Code with claude mcp add --scope user --transport http when the claude binary is on your PATH, otherwise by merging the entry into ~/.claude.json:

npm i -g @fyio/buildfyio-cli
buildfy login
buildfy mcp install claude-code --org my-team        # or: cursor | windsurf
buildfy mcp install claude-code --scopes read,deploy,admin   # admin: create/update/delete tools

Pass --org when you belong to several workspaces (the command asks in a terminal and refuses to guess in CI). The token is printed only as bfy_…last4 unless you pass --print-token. By hand, the equivalent is:

claude mcp add --scope user --transport http buildfyio https://mcp.buildfyio.com/mcp --header "Authorization: Bearer <token>"

Claude Code does not read ~/.claude/mcp_servers.json. Older CLI versions wrote the server there; buildfy mcp install claude-code now removes that stale entry and says so.

Running it locally instead

If you would rather not use the hosted server — an air-gapped setup, or a self-hosted Buildfyio — the same tools ship as a stdio server you run yourself (this is also what buildfy mcp install claude-desktop configures):

npx -y @fyio/buildfyio-mcp      # env: BUILDFYIO_TOKEN, BUILDFYIO_ORG, optional BUILDFYIO_API_URL

For client authors

The server speaks JSON-RPC 2.0 over HTTP and authenticates with OAuth 2.1 (PKCE required, dynamic client registration supported). Discovery follows the specs, so a compliant client needs nothing but the URL above:

GET https://mcp.buildfyio.com/.well-known/oauth-protected-resource
GET https://api.buildfyio.com/.well-known/oauth-authorization-server

An unauthenticated call returns 401 with a WWW-Authenticateheader pointing at the resource metadata.

AI agents →CLI →SDK →