Model Context Protocol (MCP)
The TaxBandits MCP (Model Context Protocol) server enables AI assistants to automate tax compliance workflows through natural language — filing 1099s, W-2s, W-9s, and more without manual form entry or API integration.
This guide gets you from zero to filing your first tax form in claude.ai, ChatGPT, or Grok in about five minutes. No prior MCP experience needed.
You connect by adding the server as an MCP connector in your AI client and providing your TaxBandits credentials. Your returns always file under your own TaxBandits account, identified by those credentials.
What You Can Do
- File any supported tax form with a single prompt
- Validate returns before IRS transmission
- Request and collect W-9s from contractors by email
- Generate recipient-ready PDFs
- Transmit returns directly to the IRS/SSA
- Check submission status at any time
Before You Start — Your Credentials
You need two values from your TaxBandits account:
- Client ID
- MCP API Key
To find them:
- Log in at sandbox.taxbandits.com.
- In the left sidebar, go to Settings → Credentials.
- Under API Credentials, reveal and copy your Client ID and MCP API Key. (Ignore Client Secret and User Token — this server only needs the Client ID and MCP API Key.)
Throughout this guide these combine into a single, comma-separated authentication value:
<ClientId>,<MCPApiKey>
Security: this value contains a secret (your MCP API Key). Don't share a URL that has it embedded, and don't post it in public channels.
The server URL is:
https://testapi-aimcp.taxbandits.com/mcp
Connect in claude.ai
claude.ai runs an OAuth connection flow, so it needs two things — the URL (with your credentials) and the OAuth Client ID.
Requires a paid Claude plan. Custom connectors aren't available on the free tier.
-
Go to Settings → Connectors.
-
Click Add custom connector.
-
Name:
TaxBandits -
URL:
https://testapi-aimcp.taxbandits.com/mcp?authentication=<ClientId>,<MCPApiKey> -
Leave OAuth Client ID blank.
-
Leave OAuth Client Secret blank.
-
Click Add / Connect and complete the connect prompt.
The TaxBandits tools appear once connected. You can set per-tool permissions (allow / ask / disallow) from the connector's settings.
Connect in ChatGPT
ChatGPT does not need the OAuth flow for this server — the credentials in the URL are enough.
-
Add a new plugin / custom action.
-
Authentication: choose None.
-
URL:
https://testapi-aimcp.taxbandits.com/mcp?authentication=<ClientId>,<MCPApiKey> -
Save. The tools become available.
Choosing "No auth" is correct here — the server reads your identity from the credentials in the URL, so no separate OAuth step is required.
Connect in Grok
Grok connects with the credentialed URL directly.
-
Add a new MCP server / connector.
-
URL:
https://testapi-aimcp.taxbandits.com/mcp?authentication=<ClientId>,<MCPApiKey> -
If Grok offers authentication options, choose None — identity comes from the credentials in the URL.
-
Save. The tools become available.
Verify the connection
Once connected, open a new chat and ask:
"What TaxBandits tools do you have access to?"
You should see the tools listed. Then try:
"List the tax forms this TaxBandits server supports."
If you see a list of forms come back, you're connected and ready to file. If nothing shows up, see Troubleshooting.
Authentication & transports (reference)
Your identity always comes from the two credentials in the URL — this is what makes filings post to your own account. The server obtains and refreshes OAuth 2.1 tokens from your credentials automatically; you never handle raw tokens.
The credential pair can be supplied as:
| Method | Example |
|---|---|
| Query parameter | ?authentication=clientId,apiKey |
| Header | Authentication: clientId,apiKey |
| Bearer token | Authorization: Bearer clientId,apiKey |
Two transport endpoints are available; use whichever your client supports:
| Protocol | Endpoint | Notes |
|---|---|---|
| StreamableHTTP | /mcp/ | Stateless, no connection timeouts — preferred |
| SSE | /sse | For SSE-compatible clients |
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| claude.ai: "automatic client registration is not supported" | The OAuth Client ID wasn't entered. Add d1c91ae43e2741b9952bf2cf0a7478f8 in the connector's OAuth Client ID field. |
401 Missing Authentication | No credentials in the URL. Add ?authentication=<ClientId>,<MCPApiKey>. |
401 Invalid Authentication format | The value must be exactly two comma-separated parts — Client ID, MCP API Key — with no spaces. |
| Tools don't appear after connecting | Confirm the URL ends in /mcp (or /sse) and the credentials are present, then reconnect. |
| Opening the URL in a browser shows an error / blank page | Expected — the endpoint speaks the MCP protocol to a connector, not a web browser. Paste it into the client, not a browser. |
| A tool returns a validation error before anything happens | By design — the server checks your data against the form's schema before calling TaxBandits. Call describe_form for the exact fields that form needs, then try again. |
| A tool returns an error mentioning "OAuth" or a TaxBandits status code | The request reached TaxBandits and the credentials or data were rejected on their end — not a connection problem. The message includes TaxBandits' own explanation. |
Still stuck? For API credentials, sandbox access, or integration support, contact the TaxBandits developer team.
Available Tools
Discovery Tools
| Tool | Description |
|---|---|
list_supported_forms | List all supported forms with their available operations |
describe_form | Get the complete JSON schema and field reference for any form |
Business & Recipient Management
| Tool | Description |
|---|---|
create_business | Register a payer (business or individual) to use across all filings. Returns a BusinessId for reuse. |
update_business | Correct or change an existing business's details (name, TIN, address, contact info, signing authority, form-specific fields) after creation. Identify it by BusinessId (preferred) or PayerRef. Changes apply to in-progress returns; already-transmitted returns are unaffected. |
create_recipient | Pre-register one or more recipients (payees) under an existing business. Returns a RecipientId per recipient for reuse across any later filing instead of re-entering full recipient details each time. |
update_recipient | Correct or change an existing recipient's own details (name, address, TIN, email, phone/fax) after creation. Identify each recipient by RecipientId (preferred) or PayeeRef and send the recipient's complete details with the changes applied. Use this — not update_form — for recipient corrections. Changes apply to in-progress returns; already-transmitted returns are unaffected. |
Form Filing
These universal tools work across all supported filing forms. Pass FormType (e.g. "1099-NEC") to target any form.
| Tool | Description |
|---|---|
file_form | Create and submit a return. Validates your payload locally before calling TaxBandits — schema errors are returned immediately without an API call. |
validate_form | Run TaxBandits server-side validation on a filed submission. |
update_form | Update an already-created return before it's transmitted, or add a new record to a submission. Omitting a record's RecordId adds a new record rather than editing. |
transmit_form | Transmit a validated return to the IRS/SSA. ⚠️ Irreversible — confirm before calling. |
get_form_status | Check the status of a specific submission. |
list_forms | List all returns filed for a business. |
get_form_pdf | Request PDF generation for a submission's returns. The download URL is delivered to the account's configured webhook — it is not returned inline. Requires a webhook configured on the account. |
Most forms support the full lifecycle (file → validate → transmit → status → list → pdf); a few differ (for example, extension forms are submitted directly on Create with no separate validate/transmit step). Call describe_form to see the exact operations available for any form.
TIN Matching
Verify a recipient's Name + TIN + TINType against IRS records before filing. Bulk service — up to 50 recipients per request, tied to one business. Results take up to 24 hours; poll status or configure a webhook.
| Tool | Description |
|---|---|
request_tin_matching | Submit up to 50 recipients for TIN Matching against IRS records. ⚠️ Real IRS-bound request, may incur charges — confirm with the user first. |
get_tin_matching_status | Check status by SubmissionId/RecordId, or directly by RecipientTINType + RecipientTIN. |
list_tin_matching | List TIN Matching records for a business or submission, filterable by status/date, paginated. |
cancel_tin_matching | Cancel a request — only while it's still in ORDER_CREATED status. |
Instant TIN Matching
Same idea, but single-recipient and real-time instead of bulk/async. This service must be specifically enabled on your account first — contact developer@taxbandits.com if you get an access-denied error.
| Tool | Description |
|---|---|
request_instant_tin_match | Verify one recipient's Name + TIN + TINType against IRS records immediately. BusinessNm required for TINType=EIN; FirstNm+LastNm required for SSN/ITIN. |
get_instant_tin_match_status | Check status by RecordId and/or RefId. TINStatusCode: TIN-001=SUCCESS, TIN-002=FAILED, TIN-003=ON HOLD (retry later). |
W-9 Management
W-9 collection uses a dedicated email-based workflow.
| Tool | Description |
|---|---|
request_w9_by_email | Send a secure W-9 completion link to one or more recipients by email. |
get_w9_status | Check whether a recipient has completed their W-9. |
list_w9 | List all W-9 forms, with optional filters by status, date, or business. |
get_w9 | Retrieve a completed W-9's data (available when status = COMPLETED). |
W-8BEN Management
Payer-initiated collection workflow for foreign individual payees, analogous to W-9's.
| Tool | Description |
|---|---|
request_w8ben_by_email | Send a secure Form W-8BEN completion link to one or more recipients by email. |
request_w8ben_by_text | Send a secure Form W-8BEN completion link to one or more recipients by SMS. |
Supported Forms
Use list_supported_forms to see the current list at runtime, and describe_form for any form's exact schema and available operations.
1099 Series
| Form | Description |
|---|---|
1099-NEC | Nonemployee Compensation |
1099-MISC | Miscellaneous Information |
1099-K | Payment Card and Third Party Network Transactions |
1099-B | Proceeds from Broker and Barter Exchange Transactions |
1099-G | Certain Government Payments |
1099-C | Cancellation of Debt |
1099-S | Proceeds from Real Estate Transactions |
1099-A | Acquisition or Abandonment of Secured Property |
1099-DIV | Dividends and Distributions |
1099-INT | Interest Income |
1099-OID | Original Issue Discount |
1099-PATR | Taxable Distributions Received From Cooperatives |
1099-Q | Payments From Qualified Education Programs |
1099-R | Distributions From Pensions, Annuities, Retirement Plans, IRAs, etc. |
1099-SA | Distributions From an HSA, Archer MSA, or Medicare Advantage MSA |
1099-LTC | Long-Term Care and Accelerated Death Benefits |
1099-DA | Digital Asset Proceeds From Broker Transactions |
1099 Transactions
Record individual payout events to recipients as they happen throughout the year, instead of waiting until year-end. TaxBandits accumulates a payment history per recipient, usable later to generate the applicable 1099 forms.
| Tool | Description |
|---|---|
record_1099_transactions | Record one or more payers' payout transactions to one or more recipients. ⚠️ Transactions cannot be modified once submitted — correcting one requires deleting the whole submission and resubmitting. |
get_1099_transactions | Retrieve recorded transactions by SubmissionId, or by BusinessId/PayerRef (optionally narrowed to a recipient), filterable by tax year/date range, paginated. |
get_1099_transactions_report | Get a summary report — total payment/withholding per recipient — over a date range. |
Each Business needs PayerRef, BusinessId, or TIN (any one). Each Recipient needs PayeeRef, RecipientId, or TIN (any one). Each Txn needs TxnDate, TxnAmt, and PaymentType (RENT | ROYALTY | OTHERINCOME | NEC).
1099-MISC Transactions
A separate transaction-recording service, specifically for 1099-MISC income types — its own endpoint, not the general one above.
| Tool | Description |
|---|---|
record_1099_misc_transactions | Record 1099-MISC payout transactions. Uses TypeOfPymt (RENT | ROYALTY | OTHERINCOME) + IsDirectSales. ⚠️ Cannot be modified once posted — correcting one requires deleting the whole submission and resubmitting. |
get_1099_misc_transactions | Retrieve recorded transactions by SubmissionId, or by BusinessId/PayerRef (optionally narrowed to a recipient), paginated. |
Summary & Signature Forms
| Tool | Description |
|---|---|
get_1096_pdf | Retrieve the Form 1096 annual summary PDF for a given tax year and EIN/SSN. Auto-generated by TaxBandits after transmission. |
get_w3_pdf | Retrieve the Form W-3 transmittal PDF for a given tax year and EIN. Auto-generated after W-2 transmission. EIN only — SSN is not accepted. |
request_94x_pin | Request a 10-digit Online Signature PIN from the IRS for e-filing 94x forms. Mailed to the business address, ~7–10 business days. |
update_94x_pin_request | Update an existing PIN request by SubmissionId + RecordId, before it's transmitted. |
Form 8453-EMP (94x E-Signature)
An alternative to a PIN for signing 94x e-filings.
| Tool | Description |
|---|---|
request_8453emp_by_email | Email the taxpayer an e-sign link; once signed, the preparer is emailed to co-sign. |
request_8453emp_url_payer | Get an embeddable secure URL for the taxpayer to e-sign in your own app/portal. |
request_8453emp_url_preparer | Get an embeddable secure URL for the preparer to e-sign in your own app/portal. |
5498 Series
| Form | Description |
|---|---|
5498 | IRA Contribution Information |
5498-ESA | Coverdell ESA Contribution Information |
5498-SA | HSA, Archer MSA, or Medicare Advantage MSA Information |
Note: For the 5498 family,
validate_formtakes the fullFormData(the same shape asfile_form) instead of aSubmissionId— it validates the payload before creation.
1098 Series
| Form | Description |
|---|---|
1098 | Mortgage Interest Statement |
1098-E | Student Loan Interest Statement |
1098-T | Tuition Statement |
Stock Option Forms
| Form | Description |
|---|---|
3921 | Exercise of an Incentive Stock Option Under Section 422(b) |
3922 | Transfer of Stock Acquired Through an Employee Stock Purchase Plan Under Section 423(c) |
W-2 Series
| Form | Description |
|---|---|
W-2 | Wage and Tax Statement |
ACA Series
| Form | Description |
|---|---|
1095-C | Employer-Provided Health Insurance Offer and Coverage |
1042 Series
| Form | Description |
|---|---|
1042-S | Foreign Person's U.S. Source Income Subject to Withholding |
Other Information Returns
| Form | Description |
|---|---|
1097-BTC | Tax Credit Bonds Allowed Credit |
W-2G | Certain Gambling Winnings |
94x Series (Payroll)
Aggregate employer-level payroll returns — no per-recipient records. FormData uses a different envelope; call describe_form for the exact shape.
| Form | Description |
|---|---|
940 | Employer's Annual Federal Unemployment (FUTA) Tax Return |
941 | Employer's QUARTERLY Federal Tax Return |
943 | Employer's ANNUAL Federal Tax Return for Agricultural Employees |
944 | Employer's ANNUAL Federal Tax Return (small-employer alternative to 941) |
945 | Annual Return of Withheld Federal Income Tax (non-payroll withholding) |
940-SCHR | Form 940 Schedule R — aggregate filing for CPEOs / Section 3504 Agents |
941-SCHR | Form 941 Schedule R — aggregate filing for CPEOs / Section 3504 Agents |
941-X | Adjusted Employer's QUARTERLY Federal Tax Return or Claim for Refund |
Extension Forms
Filing-deadline extensions submitted directly to the IRS on Create — no separate Validate or Transmit step.
| Form | Description |
|---|---|
8809 | Extension of Time to File Information Returns |
15397 | Extension of Time to Furnish Recipient Copies of Information Returns |
4868 | Automatic Extension of Time to File Individual Income Tax Return |
7004 | Automatic Extension of Time to File Business Income Tax Returns |
Dedicated Workflow Forms
| Form | Tools |
|---|---|
W-9 | request_w9_by_email, get_w9_status, list_w9, get_w9 |
W-8BEN | request_w8ben_by_email, request_w8ben_by_text |
1096 | get_1096_pdf (auto-generated summary — no filing required) |
W-3 | get_w3_pdf (auto-generated W-2 transmittal — no filing required) |
Online94xPINRequest | request_94x_pin (requests a 94x e-file signature PIN) |
Form8453EMP | request_8453emp_by_email, request_8453emp_url_payer, request_8453emp_url_preparer |
Standard Filing Workflow
1. list_supported_forms → confirm the form type is supported
2. create_business → register payer, save BusinessId
2a. create_recipient → (optional) pre-register recipients, save RecipientId(s) for reuse
3. describe_form → review the schema and required fields
4. file_form → submit the return (validates locally first)
5. validate_form → server-side IRS rule check
6. get_form_pdf → generate recipient copies
7. transmit_form → send to IRS/SSA (irreversible — confirm first)
8. get_form_status → verify acceptance
Example Prompts
File a 1099-NEC for tax year 2026.
Payer: Snowdaze LLC, EIN 12-3456789, 100 Main St, Austin TX 78701
Recipient: John Vendor, SSN 123-45-6789, Box 1 amount: $8,500
Send a W-9 request to vendor@example.com for my business (BusinessId: abc-123)
Check the status of my 1099-NEC submission ID: 04c5efe6-362e-44ab-bead-4473c6ea944f
List all 1098 filings for BusinessId: abc-123
Rate Limits
| Tier | Limit |
|---|---|
| Per second | 10 requests |
| Per minute | 100 requests |
| Per hour | 1,000 requests |
| Per day | 5,000 requests |
Rate-limit headers are returned with every response. If a limit is hit, the response includes retry_after_seconds.
Security & Compliance
- Encryption: TLS 1.2+ in transit; credentials are never logged.
- PII Redaction: TIN, SSN, and EIN values are masked (
***REDACTED***) in all audit logs. - Token Management: OAuth 2.1 tokens are cached and auto-refreshed; raw tokens are never exposed to clients.
- Audit Trail: Every tool call is logged with tool name, status, execution time, and client identifier.
- Account isolation: Your returns file under your own TaxBandits account, identified by your credentials.