AI Agent Protocol (MCP)

The Model Context Protocol (MCP) is Audit1's newest ingestion method, enabling AI agents to discover requirements, validate data, and submit payroll reports programmatically.

What is MCP?

MCP is an open standard (JSON-RPC 2.0 over HTTP) designed for AI agent communication. Instead of hand-coding API calls, agents dynamically discover available tools, required fields, and validation rules — then submit data through a single endpoint.

How It Works #

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   Your AI Agent  │  POST   │   Audit1 MCP     │  HTTP   │   Audit1         │
│   (LLM, Script,  │ ──────► │   Server         │ ──────► │   Platform       │
│    Automation)   │  /mcp   │                  │         │  (Processing &   │
│                  │ ◄────── │  JSON-RPC 2.0    │ ◄────── │   Reporting)     │
└──────────────────┘         └──────────────────┘         └──────────────────┘
  1. Connect — Agent sends initialize to establish an MCP session
  2. Discover — Agent calls tools/list to learn available tools
  3. Explore — Agent calls get_expected_fields and list_employer_policies to learn requirements
  4. Validate — Agent calls validate_payroll_submission to pre-check data
  5. Submit — Agent calls submit_payroll_data to submit for real
  6. Monitor — Agent calls get_submission_status and get_validation_errors to track results

MCP vs REST API #

MCP REST API
Protocol JSON-RPC 2.0 (single endpoint) REST (multiple endpoints)
Authentication Bearer token (mcp_...) Client ID + Secret headers
Primary audience AI agents & LLMs Developers & applications
Tool discovery Built-in (tools/list) Read documentation
Field discovery Built-in (get_expected_fields) Read documentation
Pre-validation Built-in (validate_payroll_submission) Submit and check errors
Sandbox mode Agent-level (sandbox: true) Key prefix (audit1_test_*)
Endpoint POST /mcp Multiple REST routes

Which should I use?

If you're building an AI agent or LLM-powered automation, use MCP. If you're building a traditional application integration, use the REST API.

Agent Types #

Type Scope Use Case
Provider All employers linked to a payroll company A payroll company's agent reporting for multiple clients (e.g., ADP agent reporting for 100+ employers)
Employer Single employer only A bookkeeper's agent reporting payroll for one company
Sandbox Same as above, but dry_run forced Development, testing, and onboarding — no data enters the real pipeline

Typical Agent Workflow #

Step 1: initialize                    → Handshake, confirm protocol version
Step 2: tools/list                    → Discover 6 available tools
Step 3: list_employer_policies        → Find active policies to report against
Step 4: get_expected_fields           → Learn required fields, class codes, states
Step 5: validate_payroll_submission   → Pre-validate rows (always dry-run)
Step 6: Fix any validation errors
Step 7: submit_payroll_data           → Submit for real (dry_run: false)
Step 8: get_submission_status         → Check Phase 1/2/3 results
Step 9: get_validation_errors         → If RED rows, get details + suggestions

Available Tools #

Tool Description Details
list_employer_policies Discover active policies for an employer Reference
get_expected_fields Required/optional fields per policy Reference
validate_payroll_submission Pre-validate rows (always dry-run) Reference
submit_payroll_data Submit payroll rows for processing Reference
get_submission_status Check Phase 1/2/3 processing results Reference
get_validation_errors Get RED row details with suggestions Reference

Next Steps #

Guide What you'll learn
MCP Authentication API keys, agent scoping, sandbox mode
MCP Tools Reference All 6 tools with schemas, examples, and error codes
REST API Traditional API alternative

Need Help? #

Email support@audit1.com with:

  • Your agent name and API key prefix (first 12 characters)
  • The tool call that failed
  • The full JSON-RPC error response