# 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: 20/hr per IP)

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

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) — company domain (e.g. acme.com)
  - invite_emails (string[]) — up to 25 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.

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 clicks the verification email.
Only valid when status = "verified".

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
  - 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 (tool: check_dns)
    4. Publish first role (tool: create_role → publish_role)

### 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."
    Poll onboarding_status every 10s. 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:      {candidate_page}
      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 but recommended)
    Ask: "Do you want candidates to apply at a custom domain like careers.yourco.com?"
    If yes: guide through CNAME setup, then call check_dns.
    If no: skip, mention the default {slug}.evidal.app URL works immediately.
    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.
    Show: ✓ Step 6 — Role published

  End with: "Your Evidal account is live. Candidates can apply at {url}."

## 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 29 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