How to Develop a WebMCP for Agents to Check EPFO Balance and Claim Status for Workers

India’s workforce increasingly expects instant answers about provident fund balances, passbook entries, and claim progress. An AI agent can make these services easier to access, but giving an agent direct access to EPFO accounts creates serious security, privacy, and reliability risks. A better architecture is a WebMCP (Web Model Context Protocol) service: a controlled web-accessible tool layer that exposes narrowly defined, auditable capabilities to agents while keeping authentication, consent, and sensitive data boundaries explicit.

This guide explains how to develop a WebMCP for agents to check EPFO balance and claim status for workers. It covers product scope, system architecture, authentication, consent, tool design, security controls, compliance considerations in India, testing, and deployment.

What a WebMCP should do

A WebMCP should not be an unrestricted browser bot that logs into the EPFO member portal on behalf of an AI model. It should be a policy-enforced integration layer that:

Receives a worker’s authenticated request or consented session.
Calls approved EPFO or authorized service interfaces where available.
Normalizes account and claim information into a stable schema.
Returns only the minimum information required for the user’s request.
Records audit events without storing unnecessary personal data.
Blocks unsupported actions, such as fund transfers or profile changes, unless separately authorized and technically supported.

The first version should be read-only. Useful capabilities include checking whether a member account is linked, retrieving the latest available balance or passbook summary, and checking the status of a claim using a claim reference number. Avoid promising real-time data: EPFO records may be delayed, unavailable during maintenance, or dependent on employer and regional processing systems.

Clarify the EPFO integration path first

Before writing code, establish how your product will obtain data. EPFO services, member authentication flows, passbook access, and claim-status systems can change. Availability of public APIs should never be assumed.

Evaluate these options in order:

1. An officially documented EPFO or government interface with explicit permission for your use case.
2. An authorized partner or regulated service provider that has a contractual right to provide the data.
3. A user-directed browser session, where the worker authenticates directly and the system does not capture or retain credentials.
4. A non-automated fallback, such as showing official EPFO instructions and linking the user to the relevant portal.

Do not scrape pages, defeat CAPTCHA, bypass OTP controls, or automate a member login without confirming that the activity is permitted. A technically successful scraper can still create legal, operational, and account-lockout risk. Build an integration-risk register covering terms of use, rate limits, consent requirements, data retention, and outage handling.

Reference architecture for a secure WebMCP

A production design should separate the AI agent from identity and EPFO connectivity. A practical architecture has these components:

Agent client: Interprets the worker’s request and asks to invoke a tool.
WebMCP gateway: Validates tool calls, identity, consent, scopes, and rate limits.
Policy engine: Decides whether the requested operation is allowed for this user, session, and data type.
Identity service: Manages login, session binding, OTP or passkey workflows, and token exchange.
EPFO connector: Communicates with an approved interface or controlled user session.
Data minimization layer: Removes unnecessary identifiers and redacts sensitive fields.
Audit service: Stores tamper-evident records of access and administrative actions.
Observability stack: Tracks latency, errors, data-source availability, and suspicious behavior.

The agent should never receive a UAN password, OTP, raw session cookie, or long-lived access token. Ideally, the connector receives a short-lived, audience-restricted token that is usable only for a particular worker, tool, and operation.

A simplified flow is:

Worker request
   -> Agent interprets intent
   -> WebMCP validates schema and consent
   -> Identity service confirms member session
   -> Policy engine authorizes read-only operation
   -> EPFO connector retrieves data
   -> Normalizer and redactor filter response
   -> Agent receives structured result
   -> Audit event is recorded

Design narrow, typed WebMCP tools

Do not expose one generic tool such as browse_epfo(query). Generic tools make prompt injection, authorization mistakes, and unpredictable data disclosure more likely. Use separate, typed tools with strict inputs and outputs.

Example tool definitions:

{
  "name": "get_epfo_balance_summary",
  "description": "Retrieve the latest available EPFO balance summary for the authenticated worker",
  "inputSchema": {
    "type": "object",
    "properties": {
      "consent_id": {"type": "string"},
      "include_breakdown": {"type": "boolean", "default": false}
    },
    "required": ["consent_id"],
    "additionalProperties": false
  }
}

{
  "name": "get_epfo_claim_status",
  "description": "Retrieve the current status of an EPFO claim for the authenticated worker",
  "inputSchema": {
    "type": "object",
    "properties": {
      "consent_id": {"type": "string"},
      "claim_reference": {"type": "string", "minLength": 4, "maxLength": 64}
    },
    "required": ["consent_id", "claim_reference"],
    "additionalProperties": false
  }
}

The tool response should distinguish confirmed values from unavailable or stale values. For example:

{
  "status": "success",
  "as_of": "2026-08-31T10:15:00Z",
  "source": "authorized_epfo_connector",
  "balance": {
    "employee_contribution": "REDACTED_OR_VALUE",
    "employer_contribution": "REDACTED_OR_VALUE",
    "interest": "REDACTED_OR_VALUE",
    "total": "REDACTED_OR_VALUE",
    "currency": "INR"
  },
  "freshness": "latest_available",
  "limitations": ["Posting delays may apply"]
}

In a real implementation, values should be numeric types or carefully formatted strings with currency validation. Never allow the model to invent a balance when the connector returns an error. Return machine-readable error codes such as AUTH_REQUIRED, CONSENT_EXPIRED, SOURCE_UNAVAILABLE, CLAIM_NOT_FOUND, and RATE_LIMITED.

Build consent into every request

EPFO information is personal financial data. Consent should be specific, informed, time-bound, and revocable. A general checkbox saying “allow the app to use my data” is weak protection.

A consent screen should explain:

Which data will be accessed: balance, contribution summary, or claim status.
Why it is needed and what the agent will display.
Whether data will be cached and for how long.
Whether a third-party connector is involved.
How the worker can revoke access or request deletion.
That the AI response may be incomplete if the official source is unavailable.

Bind consent to the authenticated worker, tool name, data scope, purpose, expiration time, and connector. Use a consent record such as:

{
  "consent_id": "cns_123",
  "subject_id": "worker_internal_id",
  "scopes": ["epfo:balance:read"],
  "purpose": "Answer worker balance question",
  "issued_at": "2026-09-03T09:00:00Z",
  "expires_at": "2026-09-03T09:15:00Z",
  "status": "active"
}

Do not use UAN as an internal database primary key. Store a separate internal subject identifier and tokenize or encrypt UAN when it must be retained for operational reasons.

Authentication and session security

Use a standards-based identity design. Depending on your product, this may include OAuth 2.0 authorization code flow with PKCE, OpenID Connect, device-bound sessions, and step-up authentication for sensitive actions.

Important controls include:

Keep credentials and OTPs exclusively in the trusted authentication interface.
Use short-lived access tokens and rotate refresh tokens.
Bind tokens to the intended audience, worker, connector, and operation.
Apply CSRF protection, secure cookies, SameSite settings, and TLS everywhere.
Prevent session fixation and revoke sessions after suspicious activity.
Never place tokens or UANs in URLs, analytics events, model prompts, or logs.
Require explicit confirmation before displaying sensitive financial amounts.

If a browser-assisted flow is unavoidable, isolate it in a hardened service. Do not send page contents wholesale to the model. Extract only fields required for the approved operation, and treat all page text as untrusted input.

Defend against prompt injection and tool abuse

An agent connected to a financial-data tool must be treated as an untrusted decision layer. The WebMCP gateway, not the model, must enforce authorization.

Use these safeguards:

Allowlist tools and parameter values.
Validate all inputs server-side with JSON Schema.
Reject requests that try to add hidden instructions or alternate destinations.
Separate system policy from data returned by the connector.
Never let EPFO page text redefine tool permissions.
Enforce per-user and per-IP rate limits.
Require human confirmation for any future write operation.
Return structured data rather than arbitrary HTML.
Add anomaly detection for repeated claim lookups or account enumeration.

A useful rule is: the model can request an operation, but only the gateway can authorize and execute it.

India-specific privacy and compliance considerations

Design for India’s Digital Personal Data Protection Act, 2023 and related rules, contractual obligations, security guidance, and applicable government-service requirements. Obtain advice from qualified Indian counsel before launch; compliance depends on your role, data flows, vendors, and processing purposes.

Your privacy program should document:

The lawful purpose and notice presented to workers.
Data categories and processing locations.
Retention and deletion schedules.
Processor and sub-processor responsibilities.
Breach detection, escalation, and notification procedures.
Data principal rights and grievance handling.
Cross-border transfer implications, if cloud or AI providers are outside India.

For India-focused deployment, also consider hosting regions, vendor access, contractual confidentiality, encryption-key ownership, and whether model providers retain prompts for training. Disable training retention where possible and redact identifiers before sending data to an external model.

Data storage and observability

The safest default is ephemeral processing: retrieve the result, display it, and delete raw records quickly. If caching improves user experience, store only the minimum fields, encrypt them, define a short TTL, and separate cache keys from direct identifiers.

Audit logs should answer who accessed what, when, for which purpose, and whether the request succeeded. They should not contain full balances, passwords, OTPs, session cookies, or raw portal HTML. Use structured events such as:

consent.created
epfo.balance.requested
epfo.balance.completed
epfo.claim.failed
session.revoked
policy.denied

Protect logs from modification, restrict access using least privilege, and define an incident-response process before production.

Error handling and user experience

EPFO data may be unavailable, delayed, or inconsistent. The agent must communicate uncertainty precisely. Good responses say “The latest available record is dated…” rather than implying live access.

Create a clear error taxonomy:

Authentication required: Ask the worker to complete the official sign-in step.
Consent expired: Request fresh, narrowly scoped consent.
Source unavailable: Explain that the service is temporarily unavailable and provide an official fallback.
No record found: Confirm the claim reference format without exposing another person’s data.
Data mismatch: Stop and route to support rather than guessing.
Rate limited: Tell the user when retrying may be appropriate.

Never reveal whether an arbitrary UAN belongs to another person. Account enumeration is a privacy vulnerability.

Testing strategy before launch

Test the WebMCP as a financial-data system, not just a chatbot feature. Include:

Unit tests for schemas, consent scope, and redaction.
Integration tests against a sandbox or approved connector.
Contract tests for connector response changes.
Security tests for token leakage, IDOR, SSRF, CSRF, and injection.
Prompt-injection tests using malicious portal text and user instructions.
Load tests with connector rate limits and outage simulation.
Privacy tests confirming that logs and model traces contain no secrets.
Accessibility and multilingual tests for Indian workers.
Human review of every user-facing error and disclaimer.

Use synthetic UAN-like identifiers and fabricated balances in development. Production data should never be copied into tickets, staging databases, or developer laptops.

A practical MVP roadmap

A low-risk launch sequence is:

1. Build a read-only claim-status tool using an approved data source.
2. Add worker authentication and one-time, scope-limited consent.
3. Implement structured errors, audit logs, and source freshness labels.
4. Add balance summary only after validating data accuracy and authorization.
5. Introduce multilingual explanations without sending extra personal data to the model.
6. Conduct an independent security and privacy review.
7. Launch with usage limits, monitoring, and a human support path.

Do not start with withdrawals, profile edits, nominee changes, or employer actions. Those capabilities require stronger transaction controls and should be treated as a separate product surface.

Recommended technology choices

The exact stack is less important than the security boundaries, but a typical implementation might use:

TypeScript, Java, or Go for the WebMCP gateway.
JSON Schema or equivalent runtime validation.
PostgreSQL for consent metadata and audit references.
Redis only for short-lived, encrypted session or rate-limit state.
A managed secrets manager backed by KMS or HSM controls.
OpenTelemetry for traces with sensitive-field filtering.
OIDC/OAuth-compatible identity infrastructure.
A policy engine such as Cedar, OPA, or equivalent authorization logic.

Use dependency pinning, software composition analysis, secret scanning, container hardening, and regular penetration testing. Keep the connector isolated from public traffic and restrict outbound network destinations.

Frequently asked questions

Can an AI agent directly log in to the EPFO portal?

It should not receive or retain a worker’s password or OTP. Use an approved integration or a user-controlled authentication flow, and verify that automation is permitted by the relevant service terms.

Is WebMCP the same as web scraping?

No. WebMCP is a controlled tool interface for agents. It can use an authorized API or connector, whereas scraping is an extraction technique that may violate terms and is difficult to secure reliably.

Can the agent show a worker’s full UAN and balance?

Only when necessary, after authentication and consent. Mask identifiers by default, minimize displayed financial data, and prevent sensitive values from entering logs or third-party model traces.

What should happen when EPFO data is unavailable?

Return a clear SOURCE_UNAVAILABLE result, show the last known timestamp only if it is safe and accurate, and direct the worker to the official EPFO channel rather than fabricating an answer.

Should the first version support withdrawals or claim filing?

No. Start with read-only balance and claim-status checks. Write operations need transaction signing, confirmation, stronger fraud controls, and a separately reviewed authorization model.

Apply for AI Grants India

Building a privacy-first WebMCP for Indian workers can create meaningful public benefit while advancing trustworthy AI infrastructure. Apply to AI Grants India for support, guidance, and funding opportunities for your India-focused AI venture.