# evidal:onboarding:v1

## Agent presentation guidelines

When presenting onboarding to a user, follow these rules:
- Lead with a one-line pitch: "I'll set up your Evidal hiring account."
- Ask for company name and the user's email BEFORE registering the MCP.
- Present each setup step as a numbered checklist with ✓/○ status.
- After each step completes, show a brief confirmation, then move to the next.
- Never dump raw JSON or API responses. Summarize key info (slug, URLs) in a clean table.
- The API key from onboarding_complete is sensitive — tell the user it's saved, don't display it in full.
- When showing the hiring-manager MCP command, format it as a copyable code block.
- Keep the tone professional but concise. No filler. One sentence per action.

## What this is

Evidal is an AI-native hiring platform. Companies post roles, candidates
apply by having their AI agent talk to Evidal's eval bot, and hiring
managers get structured scores. This MCP server creates a new company.

## MCP Server

url: https://app.evidal.ai/api/mcp/onboarding
transport: streamable-http
protocol: 2025-03-26
auth: none (rate-limited per IP: 20/hr for onboarding_start / onboarding_complete / onboarding_cancel; 120/hr for initialize, tools/list, ping and onboarding_status polls; 429 = JSON-RPC error -32002 with data.retry_after_seconds + Retry-After)

## Registration (Claude Code)

Add to `~/.claude.json` or a project `.mcp.json`:

    {
      "mcpServers": {
        "evidal-onboarding": {
          "type": "http",
          "url": "https://app.evidal.ai/api/mcp/onboarding"
        }
      }
    }

Or via CLI:

    claude mcp add --transport http evidal-onboarding https://app.evidal.ai/api/mcp/onboarding

No Authorization header needed — the onboarding server is public.

## Tools

### onboarding_start

Start a new company onboarding session. Sends a verification email. The link in it VERIFIES the request only — it does not sign the owner in (a separate dashboard sign-in email is sent by onboarding_complete).

Required fields:
  - owner_email (string, email) — the hiring manager's email
  - company_name (string) — the company name

Optional fields:
  - slug (string) — URL-safe company slug (auto-generated from name if omitted)
  - domain (string) — OPTIONAL apply hostname the company controls, e.g. evidal.acme.com (a subdomain, never the corporate apex). Leave it out to use the default candidate page https://evidal.ai/c/{slug}.
  - invite_emails (string[]) — up to 5 teammate emails to invite on completion
  - initial_role (object) — pre-configure the first role:
    - title (string, required)
    - level (string, optional)
    - ai_native_required (boolean, optional)
    - description (string, optional)
  - lever_api_key (string, optional) — Lever ATS API key. Pass with lever_subdomain to auto-connect Lever at onboarding_complete. If validation fails, the company is still created and lever_connect_result=validation_failed is returned.
  - lever_subdomain (string, optional) — Lever subdomain (e.g. `acme`). Required if lever_api_key is supplied.

Returns: { session_id, status, verification_email_sent_to, expires_at }

### onboarding_status

Poll the status of an onboarding session. Poll no more than once every 60 seconds.

Required: session_id (UUID)

Returns: { status } where status is one of:
  pending_email_verification | verified | completed | expired | cancelled

### onboarding_complete

Finalize onboarding after the user confirms the verification page.
Only valid when status = "verified".
Creates the company on the draft slug tier (see slug_tier / slug_expires_at in the response),
the optional initial role with 3 free evaluations (role_status = trial), and emails the
owner a single-use dashboard sign-in link (owner_sign_in.status).

Required: session_id (UUID)

Returns a guided setup sequence:
  - slug — the company's URL slug
  - api_key — the API key (shown ONCE — save it immediately)
  - connect.mcp_endpoint — the hiring-manager MCP server URL
  - connect.mcp_command — ready-to-paste claude mcp add command
  - links.candidate_page — where candidates can apply RIGHT NOW: https://evidal.ai/c/{slug}
  - slug_tier / slug_expires_at / slug_tier_note — draft-tier facts to relay to the user
  - owner_sign_in — { status: sent | failed | skipped } for the dashboard sign-in email
  - setup[] — ordered steps to complete company configuration:
    1. Connect the hiring-manager MCP server
    2. Upload company logo (tool: update_company)
    3. Set up custom domain — optional (tool: check_dns; needs BOTH records in setup[3].dns_records)
    4. Publish first role (tool: create_role → publish_role) — free, 3 evaluations included

### onboarding_cancel

Cancel a pending session. Frees the proposed slug. Idempotent.

Required: session_id (UUID)

## Step-by-step flow (present as a numbered checklist to the user)

Before starting, gather from the user:
  - Company name
  - Their email address
  - (Optional) preferred URL slug, domain, and first role title

Then execute:

  ○ Step 1 — Create account
    Call onboarding_start. Tell user: "Check your email for a verification link — review the request on that page and press Verify."
    Poll onboarding_status every 60s (never faster). Show: "Waiting for email verification…"
    Once verified, show: ✓ Step 1 — Email verified

  ○ Step 2 — Finalize setup
    Call onboarding_complete. Save the api_key securely.
    Show the user a summary table:
      Company:  {name}
      Slug:     {slug}
      URL:      {links.candidate_page}   (https://evidal.ai/c/{slug} — works now)
      API key:  saved (not displayed for security)
    Then show: ✓ Step 2 — Company created

  ○ Step 3 — Connect management tools
    Register the hiring-manager MCP using the returned mcp_command.
    Show the command as a copyable code block.
    Tell user: "Run this command, then come back and I'll continue setup."
    Show: ✓ Step 3 — Management tools connected

  ○ Step 4 — Company profile
    Ask for a logo URL. Call update_company to set it.
    Show: ✓ Step 4 — Logo uploaded

  ○ Step 5 — Custom domain (optional)
    Ask: "Do you want candidates to apply at your own hostname, like evidal.yourco.com?"
    If yes: set it with update_company {domain}, then guide through BOTH records from
    setup[].dns_records — CNAME <domain> → cname target AND TXT _evidal-verify.<domain> —
    then call check_dns. It reports missing_records until both resolve. The CNAME must be
    DNS-only (Cloudflare: grey cloud, not proxied). If check_dns returns legacy_cname=true the
    domain points at an older alias — still valid; tell the user no change is needed.
    Rarely check_dns returns hosting_verification.required=true: their apex is already registered
    with another account at our hosting provider, so ONE more one-time TXT record is needed —
    relay next_step verbatim (it names the record), then call check_dns again once it is added.
    next_step_kind names which sentence it is — on provider_unreachable we could not reach the
    provider, so say nothing about whether the domain is connected.
    If no: skip — candidates can apply at {links.candidate_page} right now.
    Do NOT present a "<slug>.<base-domain>" tenant subdomain as working — production does not serve one.
    Show: ✓ Step 5 — Domain configured (or skipped)

  ○ Step 6 — Publish first role
    Ask for role details (title, level, description, requirements).
    Call create_role (creates as draft). Show the draft to the user.
    Ask: "Ready to publish?" Only call publish_role after explicit confirmation.
    Publishing is free and includes 3 evaluations per role; do not steer the user to
    activate_role or start_checkout until trial_evals_remaining reaches 0, and never
    call activate_role without the user's explicit confirmation of the charge.
    Show: ✓ Step 6 — Role published

  End with: "Your Evidal account is live. Candidates can apply at {links.candidate_page}"
  (or at the verified custom domain once check_dns reports verified).

## After onboarding

Once you have the API key, switch to the hiring-manager MCP server:
  https://app.evidal.ai/api/v1/company/{slug}/hiring-manager-skill.md

That skill.md describes all 23 tools for managing roles, candidates,
team members, billing, Slack, Lever ATS, and more.

## Docs

Human-readable onboarding docs: https://app.evidal.ai/docs/mcp/onboarding
Human-readable hiring-manager docs: https://app.evidal.ai/docs/mcp
REST API reference: https://app.evidal.ai/docs/api
All docs: https://app.evidal.ai/docs