# Set up SurfIA

Official SurfIA setup instructions. Release: 2026-10-06.1.

Connect my existing or new SurfIA business to this agent for daily operations.
Read https://app.surfia.ai/agent-setup/release.json and fetch the matching
https://app.surfia.ai/agent-setup/skills/surfia/SKILL.md. Verify its SHA-256
against the release manifest before installing. Fetch over HTTPS without
forwarding credentials; do not execute an installer script.
Require this document, the manifest and the skill to have the same release
version. If they differ, retry the fetch later; do not install a mixed release.

Inspect the current client and its existing SurfIA skill/MCP installation.
Use Codex or Claude Code. Reuse a connection pointing to exactly
https://app.surfia.ai/api/agent/mcp. Preserve unrelated settings and any custom
skill: compare it with the previously installed official digest. Update an
unchanged official copy; if customized, explain the difference and preserve
the customization before replacing anything. A different server already
named surfia must not be silently replaced.

Install only the verified skill in the client's user skill directory:
`~/.agents/skills/surfia/SKILL.md` for Codex, or
`~/.claude/skills/surfia/SKILL.md` for Claude Code. Honor an explicitly
configured skill directory. Save the official digest/version beside it so a
later update can distinguish the official copy from customization.

Configure the remote HTTP MCP using the client's own configuration command:

- Codex: `codex mcp add surfia --url https://app.surfia.ai/api/agent/mcp`.
  If the existing connection needs login, use `codex mcp login surfia`.
- Claude Code: `claude mcp add --transport http --scope user surfia https://app.surfia.ai/api/agent/mcp`,
  then `claude mcp login surfia`. Older clients can authenticate through `/mcp`.

If browser authorization reports `invalid_client` for an existing matching
connection, its cached legacy registration may have expired. Explain that
login must restart, then use `codex mcp logout surfia` followed by
`codex mcp login surfia`, or `claude mcp logout surfia` followed by
`claude mcp login surfia`. These commands preserve the server configuration
and unrelated connections. Do not delete or replace configuration to recover.

Use the real browser authorization. The owner signs in or creates an account
in SurfIA, reviews the business, permissions and local callback, and approves
or denies. Google, anti-bot verification, passwords and channel activation
are browser-only. Do not ask the owner to paste a password or SurfIA session
token, do not reuse a dashboard bearer, and do not automate consent. Only
open the authorization URL generated by this local client's login command.
For headless login, use the client's `--no-browser` instructions and enter
the callback locally, never in a shared conversation or log.

Read the installed skill. When the client exposes its MCP tools, call
`surfia_whoami` and `surfia_onboarding_get`. If a client reload is necessary,
say that setup is waiting for reload; do not claim completion. If the service
is disabled or a permission is missing, explain the returned state rather
than trying another credential or an undocumented endpoint.

Completion means both checks succeeded for the business the owner intended.
An incomplete account remains paused for the existing browser checklist.
Messages and orders are proposals only: the owner reviews the complete card
in SurfIA and confirms it. Connecting an agent activates no customer channel.