How to Build a WebMCP for Agents to Search Jobs

AI agents can make job discovery faster, but connecting an agent directly to a public employment portal requires careful handling of search filters, consent, personal data, rate limits, and changing web interfaces. This guide explains how to build a WebMCP for agents to search for open job positions on the National Career Service portal (NCS), using a controlled tool layer rather than giving an LLM unrestricted browser access.

The goal is a read-only, auditable experience: an agent interprets a candidate’s request, invokes structured search tools, returns relevant openings with source links, and leaves application submission to the user.

What Is WebMCP?

WebMCP is a model-context interface that exposes web capabilities to AI agents through well-defined tools. Instead of asking an agent to guess which buttons to click, a WebMCP describes operations such as:

Search jobs by keyword, location, qualification, sector, salary, and experience.
Retrieve job details from a known listing.
Apply pagination, sorting, and result limits.
Return canonical URLs and freshness information.

In this design, the agent handles intent and conversation, while your WebMCP server validates parameters, calls an approved NCS integration, normalises results, and enforces policies.

A useful separation is:

User → AI agent → WebMCP tools → NCS adapter → National Career Service
                         ↓
                  validation, logs, policy

The WebMCP should not claim to be an official NCS service unless you have explicit authorisation. Clearly label it as an independent assistant or integration, and link every result back to the original NCS page.

Confirm the National Career Service Access Model First

Before writing code, determine how your system can access current NCS listings. Prefer, in order:

1. An official API or documented integration supplied by the portal or its operator.
2. A permitted partner or government data feed with written usage terms.
3. A user-directed browser workflow that respects the portal’s terms, robots guidance, authentication boundaries, and rate limits.

Avoid designing around reverse-engineered private endpoints, CAPTCHA bypasses, session theft, or high-volume scraping. If an official machine-readable interface is unavailable, build an adapter that uses only permitted public pages and implement conservative caching. Ask the portal operator for permission when the use case involves sustained traffic or redistribution of listing data.

Also verify whether search results include personal information, employer contact details, or fields with usage restrictions. Store the minimum data required to answer a search and preserve attribution, timestamps, and source URLs.

Define the Search Contract

An agent needs a stable schema, not a page-specific collection of labels. Define a request model with explicit limits and enumerations:

{
  "query": "data analyst",
  "location": "Bengaluru",
  "state": "Karnataka",
  "qualification": "graduate",
  "experience_years": {"min": 0, "max": 3},
  "sector": "IT and ITES",
  "employment_type": "full-time",
  "salary_min_inr": 300000,
  "posted_within_days": 30,
  "page": 1,
  "page_size": 10
}

Use a strict JSON Schema or equivalent validation layer. Important rules include:

Limit page_size, for example to 25 or fewer.
Reject negative salary and experience values.
Use ISO dates internally, even if the portal displays local formats.
Normalise Indian locations without silently changing user intent.
Treat missing filters as unspecified, not as “any value” injected by the model.
Prevent arbitrary URL, header, SQL, or selector input from reaching the adapter.

Return a predictable response:

{
  "results": [
    {
      "id": "ncs:example-id",
      "title": "Junior Data Analyst",
      "organisation": "Example Employer",
      "location": "Bengaluru, Karnataka",
      "employment_type": "Full-time",
      "experience": "0–3 years",
      "salary": "As per employer policy",
      "posted_date": "2026-08-15",
      "source_url": "https://example.gov.in/job/example-id",
      "retrieved_at": "2026-09-03T10:00:00Z"
    }
  ],
  "total_estimate": 42,
  "page": 1,
  "page_size": 10,
  "warnings": []
}

Never let the model invent missing salary, employer, location, or closing-date values. Represent unknown values as null or “Not specified”.

Design the WebMCP Tools

Keep tools narrow and composable. A practical initial tool set is:

`search_ncs_jobs`

Searches published vacancies using validated filters. It should be read-only and return concise structured results.

`get_ncs_job`

Fetches the complete details for one result by an internal listing ID or an allow-listed source URL. Revalidate that the URL belongs to the approved NCS domain.

`explain_search_filters`

Optional tool that translates portal-specific terms into user-friendly explanations. It should not fetch data and can be implemented locally.

`open_source_listing`

Returns a link for the user to review. It should not submit an application, upload documents, send messages, or create an account without a separate, explicit user-controlled flow.

A tool definition should describe required fields, permitted values, output shape, failure modes, and side effects. State clearly that search_ncs_jobs may access external data and that results can become stale.

Example conceptual definition:

{
  "name": "search_ncs_jobs",
  "description": "Find open positions on the National Career Service portal. Read-only; does not apply for jobs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "maxLength": 120},
      "location": {"type": "string", "maxLength": 80},
      "page": {"type": "integer", "minimum": 1, "maximum": 20},
      "page_size": {"type": "integer", "minimum": 1, "maximum": 25}
    },
    "required": ["query"]
  }
}

Use an allow-list for tool names. Do not expose internal database queries, arbitrary HTTP requests, browser JavaScript execution, or credential-bearing operations to the agent.

Build an Adapter Layer, Not a Scraper in the Agent

The NCS adapter should isolate portal-specific logic from the WebMCP contract. Its responsibilities include:

1. Constructing requests through an approved access method.
2. Handling pagination and transient errors.
3. Parsing fields into your canonical schema.
4. Detecting layout or schema changes.
5. Applying freshness and deduplication rules.
6. Returning source attribution and warnings.

For a permitted HTML integration, use a server-side HTTP client with strict timeouts, a descriptive user agent, bounded response sizes, and rate limiting. If a browser is necessary because the public search interface requires JavaScript, use a managed browser only within the portal’s rules. Never pass raw page content directly into the model; first extract and validate fields.

A robust fetch flow is:

validate input
→ check cache
→ call approved NCS source
→ parse and normalise
→ validate output
→ remove duplicates
→ attach source and timestamp
→ return bounded results

Add contract tests using saved, legally obtained fixtures. When selectors fail or required fields disappear, fail closed with a useful warning instead of returning plausible-looking empty or fabricated results.

Agent Instructions and Grounding

The agent prompt should constrain behaviour. For example:

Ask a clarifying question when the request has no meaningful search term or location.
Use search_ncs_jobs for current listings rather than relying on memory.
Never state that a job is still open unless the source provides current status.
Show the retrieval time and original listing link.
Preserve “not specified” values.
Do not apply, contact employers, or handle sensitive documents through the search tool.
Summarise only fields returned by the tool.

For ambiguous requests such as “government jobs near Delhi,” clarify whether the user means Delhi NCT, nearby NCR cities, central government roles, or all sectors. For India-specific searches, support states, union territories, districts, PIN codes where available, and common spelling variants, but display the portal’s actual location value.

Security, Privacy, and Responsible Use

Job search can involve sensitive information, especially if users provide disability status, caste category, age, phone numbers, identity documents, or CVs. A read-only search assistant should not need most of this data.

Implement the following controls:

Do not collect Aadhaar, PAN, passwords, or identity documents for a job search.
Redact personal data from logs and analytics.
Encrypt data in transit and at rest where user data is stored.
Set short retention periods for conversations and search history.
Obtain consent before saving preferences or sharing data with third parties.
Provide deletion and correction mechanisms appropriate to your service.
Use role-based access for operational dashboards.
Validate and sanitise URLs before rendering them.
Treat listing text as untrusted content to reduce prompt-injection risk.

Under India’s Digital Personal Data Protection Act, 2023 and other applicable requirements, document your purpose, notices, consent or other lawful basis, retention, and grievance process with qualified legal advice. Do not imply government endorsement, and provide an accessible route to the authoritative portal.

Reliability and Freshness

A search result is not the same as a confirmed vacancy. Listings may close between retrieval and application. Include:

retrieved_at timestamp in IST and machine-readable UTC where useful.
Source publication date and closing date when supplied.
A freshness warning after a configurable threshold.
A “verify on NCS” action before the user relies on a result.
Duplicate detection based on source ID, canonical URL, title, employer, and location.

If the upstream portal is unavailable, say so. A good fallback is to return cached results labelled as cached, not to silently substitute data from an unverified site.

Testing Strategy

Test at four levels:

Schema tests

Check invalid locations, oversized queries, unsupported filters, pagination limits, null fields, and malformed dates.

Adapter tests

Use fixtures for normal pages, zero results, duplicate results, changed markup, missing salary, expired listings, rate-limit responses, and timeouts.

Agent evaluation

Create realistic prompts such as:

“Find entry-level accounting jobs in Pune posted in the last 14 days.”
“Show IT jobs in Telangana requiring a diploma and no experience.”
“Find jobs near Kochi, but do not show roles requiring relocation.”

Measure tool-selection accuracy, clarification quality, filter fidelity, citation coverage, hallucination rate, and whether the agent attempts prohibited actions.

Security testing

Test prompt injection in employer descriptions, malicious links, SSRF attempts, oversized responses, repeated tool calls, credential exposure, and cross-user data leakage. Add per-user quotas, circuit breakers, and monitoring for unusual query volume.

Deployment Blueprint

A production deployment can use:

An agent runtime that supports structured tool calls.
A WebMCP gateway for authentication, schema validation, quotas, and audit events.
A stateless NCS adapter service.
Redis or another cache for short-lived search responses.
PostgreSQL or equivalent storage for approved metadata, not unnecessary personal data.
OpenTelemetry-compatible logs and traces with sensitive fields filtered.
A secrets manager for integration credentials.

Keep the gateway and adapter on private network paths where possible. Apply outbound allow-listing so the adapter can contact only approved domains. Set connection, read, and total request timeouts. Use retries only for safe, idempotent reads, with exponential backoff and jitter.

Monitor latency, upstream error rates, parser failures, cache hit rate, result freshness, empty-result rate, and tool policy violations. Alert when the portal’s structure changes or when a sudden drop in results suggests an integration problem.

A Practical Build Sequence

A low-risk implementation plan is:

1. Write the use-case, data-flow, and portal permission assumptions.
2. Define the canonical search and result schemas.
3. Build a mock NCS adapter and validate agent behaviour offline.
4. Add the approved live access method with strict quotas.
5. Implement source links, timestamps, warnings, and read-only safeguards.
6. Add privacy controls, logging redaction, and deletion workflows.
7. Run schema, reliability, security, and agent evaluations.
8. Launch to a small cohort and review false positives and stale results.
9. Add features such as saved searches only after consent and retention controls are ready.

Do not start with autonomous applications. Searching and explaining listings is substantially safer than submitting forms, uploading resumes, or sending messages. Those actions require stronger identity, consent, confirmation, and transaction controls.

Common Mistakes to Avoid

Giving the model unrestricted browser or HTTP access.
Scraping undocumented endpoints without checking permissions.
Returning listings without source URLs or retrieval times.
Treating an empty page as proof that no jobs exist.
Inventing salary, eligibility, or closing-date information.
Logging complete user prompts that contain personal data.
Allowing arbitrary pagination or repeated calls to exhaust the upstream portal.
Presenting an independent assistant as an official government service.
Mixing search, account login, and application submission into one tool.

FAQ

Can I build a WebMCP using only public NCS web pages?

You may be able to build a limited integration, but first check the portal’s terms, robots guidance, copyright and data-use conditions, and any applicable permission requirements. Prefer an official API or written partnership for ongoing traffic.

Should the agent apply for jobs automatically?

No. Keep the first version read-only. Let users open the authoritative listing, review eligibility, and complete any application themselves unless you have designed a separately authorised, consent-driven workflow.

How often should job data be refreshed?

It depends on portal terms, traffic limits, and vacancy volatility. Use short-lived caching for search results, show retrieval times, and always direct users to verify the live listing before applying.

What should happen when a listing has missing fields?

Return the listing with explicit unknown values such as “Not specified.” Never infer salary, qualification, employer, or job status from the title or description.

Apply for AI Grants India

Building a responsible WebMCP for employment discovery is a strong applied-AI project when it combines measurable public value with privacy, safety, and reliable engineering. Apply to AI Grants India to explore support for your India-focused AI product.