# Faable MCP server > Connects Claude, Cursor and any MCP client to Faable Deploy and Faable Auth: read apps, deployments, build and runtime logs, traffic and domains, and deploy; see who logs in to your apps, count and find users, and suspend them — without leaving the editor. Endpoint: https://mcp.faable.com/mcp (Streamable HTTP). Sign in with OAuth: an MCP client discovers it from the 401 (`resource_metadata`), opens a Faable sign-in and consent screen where the user picks one project and allows what the agent may do (`deploy:read`, `deploy:deploy`, `deploy:write`, and `auth:read` / `auth:write` for the Faable Auth tools). Or send a Faable API key: `Authorization: Bearer ` (project settings → API keys). Either way it acts on one project only. - `https://mcp.faable.com/mcp/` pins every call to one project. - `?mode=write` adds the reversible writes (create apps, set secrets, add domains, retry or cancel builds, change deploy settings). Nothing destructive is exposed. - `?readonly=1` exposes reads only. - Local alternative, no key: `npx -y @faable/faable mcp` (uses `faable login`). ## Tools - `whoami`: The Faable account this server acts as, the active project and its Auth tenant, and `server_version` — the Faable CLI version this MCP server runs. Use it first when unsure whether the user is logged in or which project is active, or to check which version is serving. - `list_projects`: The user's Faable projects. Apps, domains and Auth tenants live in a project; pass its id as `project` to the other tools. - `list_apps`: The apps of a project, with their live phase, URL and linked repository. Start here to find the app the user means. - `get_app`: One app: phase, URL, repository, deploy branch and mode, detected stack, and its newest deployment (which may have failed while an older one keeps serving). Use it to answer 'is my app up?' or 'what is deployed?'. - `list_deployments`: Recent deployments of an app, newest first, with phase, commit and the first line of any failure reason. Use it to find the deployment behind 'my last deploy failed'. - `get_deployment`: Everything recorded about one deployment: phase, commit, detected stack, the runnable artifact, the FULL failure reason and, when it failed, `fault` — whether it is the user's to fix (`user`) or Faable's (`platform`). Without `deployment`, the newest one of the app. - `get_build_logs`: The build output of a deployment — the first thing to read when a deploy failed and the user asks why. The cause is usually at the end. Without `deployment`, the newest one that was not cancelled. - `get_runtime_logs`: What the running app printed (last 24 hours, up to 200 lines). Use it when the app is up but misbehaving, or crashes after starting. A deployment retired more than a day ago has none — read its build logs instead. - `get_app_traffic`: Requests the app served: status codes, busiest paths and failing paths. Trails reality by up to 15 minutes. - `get_usage`: This billing period's usage of a project: plan, apps, domains, deployments and egress. - `get_quota`: Today's deploy allowance of a project and the builds held waiting for it. Use it when a deploy did not start: a held build is waiting, not failing. - `list_domains`: Custom domains of an app and whether their DNS is verified. Without `app`, every domain of the project with the app it serves: `app_id: null` is a domain linked to no app (its app was deleted), which answers DOMAIN_NOT_LINKED until attach_domain links it. `redirect` names the domain it sends every request to (the www half of a pair, or an alias); null when it serves its app. - `check_domain`: DNS diagnostic of one custom domain: the CNAME it expects, what DNS answers today, and why it is not verified yet. `prevalidation_cname.ready` says whether the optional `_acme-challenge` record is in place, so the certificate is issued without waiting for the CNAME; `status.tls_state` is `ok` once the edge serves a valid certificate for the domain (`status.tls_expires_at`). - `list_secrets`: The environment variables set on an app. Names only — values are masked and this tool can never reveal them. Use it to check whether a variable the app needs is set. - `list_auth_tenants`: The Faable Auth tenants (user directories) of a project. Most projects have one and every Auth tool uses it; with several, pass the right one as `tenant`. - `list_auth_logins`: Who logged in to the app's Faable Auth, newest first: one row per login with the user's email, when, from which IP and with which method. Answers 'who logged in recently?' or 'did X log in today?'. For 'how many', use count_auth_users. - `count_auth_users`: How many users of the Auth tenant match: logged in since a time ('how many users logged in today / this week'), signed up since a time ('how many sign-ups this month'), suspended, or all of them. Counts users, not logins. - `list_auth_users`: Users of the Auth tenant. Find one by email or text, list the suspended ones, or sort: `-last_login` (most recent login first), `last_login` (longest without logging in), `-logins_count` (most active), `-createdAt` (newest sign-ups, the default). Sorting by last_login leaves out users who never logged in. - `get_auth_user`: One user of the Auth tenant by id or email: profile, verification, suspension (and why), last login and login count, the social identities they sign in with, and `credentials` — the email/username they actually TYPE at the database (password) login. That login identifier can differ from the profile `email`; when it does, a login failing with the profile email is the bug. Use it to confirm who a user is before suspending them, or to see why they can't log in (together with list_auth_logs). - `diagnose_auth_login`: Given the exact email or username a person is trying to log in with, explain in one call whether it signs anyone in. `logs_in: true` → it is a real login identifier (so a failure is the password or a suspension, not the identifier). `logs_in: false` with `profile_email_only` populated → a user has that address as their PROFILE email but logs in with a different identifier (the usual trap: the address they were given is not the one on the account); `login_identifiers` lists what they must actually type. `suggestions` offers near matches when nothing matched. Use this first for 'X cannot log in'. - `list_auth_logs`: The Auth tenant's audit log, newest first: logins, failed logins (`status: failed`), sign-ups, password resets, admin changes (`type` prefix `admin.user`). Filter by user to answer 'why can't X log in?' — the failed attempts say why. On a failed login no user resolves, so each row also carries `attempted_identifier`: the email/username the person actually typed (diagnose_auth_login turns that into the account they should be using). - `list_auth_sessions`: The devices a user is signed in on (one row per login session): IP, device, last activity and whether it is still active. - `list_auth_connections`: How users can log in to the Auth tenant: social providers (Google, GitHub…), passwordless (email or SMS codes) and username/password, and which are enabled. - `list_auth_clients`: The applications (OAuth clients) of the Auth tenant: web apps, SPAs, native apps and machine-to-machine clients. - `list_github_repos`: The GitHub repositories Faable can deploy: those the Faable GitHub App is installed on. Use it before create_app to find the repository the user means. When the app is not installed (or the repository is missing), give the user `install_url` — installing it is a step in their browser. - `deploy_app`: Build and deploy the latest commit of the app's deploy branch on Faable's servers — the same as a git push. Nothing is uploaded from this machine. With `wait`, returns once it is live (with the URL) or failed (with the reason and whether it is the user's code or Faable's); without it, returns the deployment id at once. Only for apps with push-to-deploy. - `list_auth_roles`: Roles of the Auth tenant and how many API permissions each grants. A role assigned to a user gives them its permissions in tokens for APIs with RBAC on; team roles grant none. Use get_auth_role for what one role grants and who holds it. - `get_auth_role`: One role of the Auth tenant, by id or exact name: the API permissions it grants (with their API) and the users it is assigned to. - `get_auth_user_access`: What a user of the Auth tenant may do: the roles assigned to them and the API permissions those roles grant, with the role behind each one. Answers 'why can (or can't) X do Y?'. A token carries the permissions the client requests that the user holds, for APIs with RBAC on. - `list_auth_apis`: APIs (resource servers) of the Auth tenant: the audience each token is issued for, its token dialect, whether RBAC is on and how many permissions its catalog has. - `create_app` (mode=write): Create an app from a GitHub repository in a project, link it and start its first deploy (the dashboard's Create & connect). Needs the Faable GitHub App installed on the repository; if the link fails, the new app is removed and the error says what to fix. - `redeploy` (mode=write): Rebuild a failed deployment from the source it recorded. Without `deployment`, the newest failed one. Refused for code older than what production serves. - `cancel_deployment` (mode=write): Stop a deployment that is still queued or building. Production keeps serving what it served. Without `deployment`, the one in flight. - `set_secrets` (mode=write): Add or update environment variables of an app. When the app is running, it restarts to apply them (only if a value changed); if its last deployment failed at runtime and nothing is running, Faable redeploys it with the new variables. Returns the names added, updated and unchanged — never the values — and `redeploy`: null when there was nothing to relaunch; otherwise `status` is `started` (follow `deployment_id` with get_deployment), `needs_rebuild` (the last deployment failed to build: retry `failed_deployment_id` with redeploy) or `not_started` (the platform refused the relaunch: retry it with redeploy to see why). - `add_domain` (mode=write): Attach a custom domain to an app. Returns the CNAME record the user must create at their DNS provider; Faable verifies it and issues the certificate on its own. If the domain already serves traffic somewhere else, tell the user to create `prevalidation_cname` (`_acme-challenge.` CNAME) FIRST and switch the main CNAME only once check_domain shows it ready: the certificate then exists before traffic moves, with no TLS gap. If it says the domain is already in this project, use attach_domain instead: adding it again cannot work. - `attach_domain` (mode=write): Link a custom domain of the project to an app: one left linked to no app (deleting an app leaves its domains in the project, answering DOMAIN_NOT_LINKED), or one moving from another of the project's apps. It keeps its id, its CNAME target and its certificate: nothing changes at the DNS provider. Use it instead of add_domain when add_domain says the domain is already in this project. - `set_domain_redirect` (mode=write): Make a custom domain send every request to another domain of the same project (GET → 301, other methods → 308, path and query kept), e.g. www.example.com to example.com, or an old name to the new one. `target: null` stops it: the domain serves its app again. The target must be a domain of the project that serves (no chains). Deleting the target later deletes the domains that redirect to it. DNS and certificate do not change. - `configure_repo` (mode=write): Change the deploy branch, the monorepo root directory ("" clears it) or the deploy mode (push: every push; ci: once CI tags a release; workflow: the repo's own GitHub workflow). Applies to the next deploy. - `link_repo` (mode=write): Link a GitHub repository to an app that already exists, so a push deploys it (for a new app, create_app does both). What is live keeps serving until the next push — linking starts no deploy. Needs the Faable GitHub App installed on the repository; if not, the error says what to fix. - `suspend_auth_user` (mode=write): Suspend one user of the Auth tenant: they can no longer log in, and their sessions and refresh tokens stop working (access tokens already issued live until they expire). Reversible with reinstate_auth_user. Confirm with get_auth_user that it is the right person first, and say why in `reason` — it is recorded on the user. - `reinstate_auth_user` (mode=write): Lift the suspension of a user: they can log in again. - `revoke_auth_sessions` (mode=write): End every active session of a user (the 'sign out of all devices' button): they have to log in again on each device. Access tokens already issued live until they expire. - `update_auth_client_fields` (mode=write): Declare which custom profile fields the users of one Auth application may write on themselves (auth-js `updateProfile`, stored in user_metadata["faable.com/fields"]). `add` takes `key`, `key:string:120` or `key:enum:a,b,c`; re-adding a key replaces it. `inherit: true` drops the app's own list and uses the tenant's again. An app's own list replaces the tenant's for that app. Only the fields: the app's URLs and settings are not changed here. - `update_auth_client_login` (mode=write): Choose which login methods one Auth application offers: which connections (by id or name, as list_auth_connections shows them) and whether the passkey button appears. `only` keeps exactly those connections and removes the rest; `disable`/`enable` change one at a time. A removed connection is refused at /authorize too, not just hidden. `passkey` needs the Pro plan. `inherit: true` drops the app's own settings and follows the tenant's again. Settings not mentioned keep their current value. - `send_password_setup` (mode=write): Send a user the email (or code) to set or reset their password — to invite a user created by hand, or to unblock one who forgot it. - `update_auth_user` (mode=write): Change a user's profile: `email`, `name`, `email_verified`. Changing `email` also moves their database login identifier (the email they type at the password login) so sign-in keeps working — pass `profile_only: true` to change only the profile email and leave the login identifier. Use this when someone cannot log in because the address they were given is not the one on their account. Confirm the person first with get_auth_user. - `set_auth_user_password` (mode=write): Set a user's database password directly, to a value you choose or one this tool generates. Use it only when the person cannot receive a password-setup link at all (e.g. the email on the account does not exist) — with a link they pick their own password and it never passes through anyone else. Pass `generate: true` to get a strong password back once, or put the exact password in `password`. The password is sent to the CLI over stdin, never in the command line; it is returned only when generated. - `get_auth_recovery_link` (mode=write): Mint a fresh password-reset link for a user and return it, so you can hand it over by another channel when the reset email will not reach them (e.g. the address on the account is not a real inbox). This ALSO sends the standard reset email. The link lets whoever holds it set the password, so treat it like a password; it works once, until used or expired. Returns `link` (email channel only), `ticket_id` and `channel`. Docs: https://faable.com/docs/cli#mcp-server