Agent Integration

Claude MCP Server

Work References provides an MCP (Model Context Protocol) server that exposes verification and onboarding tools directly to Claude Desktop and Claude Code.

Configuration

Add this to your Claude Desktop or Claude Code MCP settings:

{
  "mcpServers": {
    "workreferences": {
      "command": "npx",
      "args": ["@workreferences/mcp-server"],
      "env": {
        "WORKREFERENCES_API_URL": "https://www.workreferences.org",
        "WORKREFERENCES_API_KEY": "rp_your_key_here",
        "WORKREFERENCES_SIGNING_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

Example Conversation

OpenAI GPT Actions

Connect Work References to a custom GPT using the OpenAPI spec and AI plugin manifest.

1. Go to GPT Builder > Configure > Actions
2. Click Import from URL
3. Enter: https://www.workreferences.org/openapi.json
4. The spec defines all public endpoints. For reference creation, add your API key in the authentication settings.

The AI plugin manifest at /.well-known/ai-plugin.json provides automatic discovery for compatible platforms.

LangChain / LlamaIndex

Use Work References as a tool in your Python agent framework.

from langchain.tools import tool
import requests

@tool
def verify_reference(reference_id: str) -> dict:
    """Verify a Work References employment reference by UUID.
    Returns gold (fully verified), silver (signature valid,
    DNS not found), or invalid (tampered)."""
    res = requests.get(
        f"https://www.workreferences.org/api/verify/{reference_id}"
    )
    return res.json()

@tool
def check_dns(domain: str) -> dict:
    """Check if a domain has a Work References DNS TXT record."""
    res = requests.get(
        "https://www.workreferences.org/api/dns/check",
        params={"domain": domain},
    )
    return res.json()

@tool
def create_reference(
    candidate_name: str,
    role: str,
    dates: str,
    text: str,
    signing_password: str,
) -> dict:
    """Create a signed employment reference via the Work References API."""
    res = requests.post(
        "https://www.workreferences.org/api/partners/references",
        headers={
            "Content-Type": "application/json",
            "x-api-key": "rp_your_api_key_here",
        },
        json={
            "candidateName": candidate_name,
            "role": role,
            "dates": dates,
            "text": text,
            "signingPassword": signing_password,
        },
    )
    return res.json()

Agent-Guided Onboarding

How an AI agent walks a user through the complete Work References setup flow:

1. Account creation: Direct the user to register their domain with a Work References implementation. They enter their domain + work email and verify via email link. This must happen in a browser.
2. Complete signup: User clicks the email verification link and sets their signing password. The system generates Ed25519 keys and shows the DNS record to add.
3. Detect registrar: Use detect_dns_provider (or resolve nameservers manually) to identify whether they use Cloudflare, Namecheap, GoDaddy, etc.
4. DNS setup instructions: Use get_registrar_guide to show registrar-specific steps with common gotchas.
5. Verify propagation: Poll check_domain_dns until found: true and valid: true. DNS propagation times vary: Cloudflare ~5 min, Namecheap ~30 min, GoDaddy 1-4 hours.
6. Generate API key: Direct the user to Settings > API Keys to create a key for programmatic access, or help them create their first reference from the dashboard.