MCP Overview
Enable AI agents to report payroll data via the Model Context Protocol
🤖 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) │
└──────────────────┘ └──────────────────┘ └──────────────────┘- Connect — Agent sends
initializeto establish an MCP session - Discover — Agent calls
tools/listto learn available tools - Explore — Agent calls
get_expected_fieldsandlist_employer_policiesto learn requirements - Validate — Agent calls
validate_payroll_submissionto pre-check data - Submit — Agent calls
submit_payroll_datato submit for real - Monitor — Agent calls
get_submission_statusandget_validation_errorsto 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 + suggestionsAvailable 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 [email protected] with:
- Your agent name and API key prefix (first 12 characters)
- The tool call that failed
- The full JSON-RPC error response
Updated 1 day ago