# ImmigrationLayer: Developer Docs (full reference)

> Setup, tool reference, and examples for the ImmigrationLayer MCP server. Eight tools, every
> data answer dated and cited. Not legal advice.

## Quick start

### Claude Code

Adds the server as a remote MCP connector over Streamable HTTP.

```
claude mcp add --transport http immigration-layer https://immigrationlayer.com/mcp
```

### Cursor

Add to .cursor/mcp.json. Cursor cannot sign in through the connector flow yet, so it reaches the four free tools only.

```
{
  "mcpServers": {
    "immigration-layer": {
      "url": "https://immigrationlayer.com/mcp"
    }
  }
}
```

### curl (current MCP)

MCP 2026-07-28 carries version and capabilities on every request. This calls check_form_edition without a session or Authorization header.

```
curl https://immigrationlayer.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: check_form_edition" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_form_edition",
      "arguments": { "form": "I-765" },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "curl", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
```

### curl (compatibility)

Older clients can send this bare tools/call request without current-version metadata. For new integrations, use the current MCP example.

```
curl https://immigrationlayer.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "check_form_edition", "arguments": { "form": "I-765" } }
  }'
```

## Tools

Generated from the same zod schemas workers/mcp registers each tool with.

### `check_form_edition`

Returns the edition of one USCIS form that USCIS accepts today, with its accept-from and reject-from dates. Use it to check which edition of a form USCIS accepts, with the date of that answer. If USCIS has announced a newer edition it does not accept yet, announced_edition gives that edition and its accept-from date. For edition changes across all forms since a date, use list_form_changes. Covers I-90, I-129, I-130, I-131, I-140, I-485, I-539, I-765, and N-400; any other form returns not_found. Free, no sign-in required. Limit: 20 calls per minute per IP, then rate_limited. Not legal advice. Source: the form's page on uscis.gov, or a dated web.archive.org capture of that page.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `form` | `string` | Yes | USCIS form number exactly as USCIS writes it, uppercase with the hyphen, e.g. "I-765". "i765" and "I765" do not match |

```
check_form_edition({ form: "I-765" })
```

```json
{
  "data": {
    "form": "I-765",
    "edition_date": "09/15/26",
    "accept_from": "2026-09-15",
    "reject_from": null,
    "announced_edition": {
      "edition_date": "10/01/26",
      "accept_from": "2026-10-01"
    }
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `list_form_changes`

Lists the form edition changes and the USCIS newsroom and Federal Register alerts ImmigrationLayer has recorded on or after a date, newest first. Edition changes cover the forms check_form_edition lists. Use it to catch up on what changed since a last check. For one form's current edition, use check_form_edition. To find alerts by keyword, use search_alerts. Returns at most 100 form edition changes and 100 alerts per page. Pass next_cursor as cursor, with the same since, to continue until next_cursor is null. Empty lists on the first page mean nothing was recorded since that date. Free, no sign-in required. Limit: 20 calls per minute per IP, then rate_limited. Not legal advice. Sources: uscis.gov form pages or dated web.archive.org captures of them, USCIS newsroom alerts, and Federal Register notices. The top-level source URL identifies the exact aggregate query, including the page cursor. Each alert and form change keeps its own source URL and content hash.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | `string` | Yes | ISO 8601 date or date-time, e.g. "2026-08-01" or "2026-08-01T09:30:00Z"; returns changes on or after this instant. A date means midnight UTC; a date-time without an offset is UTC. |
| `cursor` | `string` | No | Opaque navigation cursor from the preceding page's next_cursor. Omit for the first page. |

```
list_form_changes({ since: "2026-08-01" })
```

```json
{
  "data": {
    "form_editions": [
      {
        "kind": "inserted",
        "changed_at": "2026-09-15T00:00:00Z",
        "form": "I-765",
        "edition_date": "09/15/26",
        "accept_from": "2026-09-15",
        "reject_from": null,
        "source_url": "https://www.uscis.gov/i-765",
        "content_hash": "sha256:example"
      }
    ],
    "alerts": [
      {
        "id": "alert_123",
        "published_at": "2026-08-14T00:00:00Z",
        "title": "USCIS to publish new editions of Form I-539 and Form I-765",
        "url": "https://www.uscis.gov/newsroom/alerts/example",
        "source": "uscis_newsroom",
        "summary": null,
        "forms_json": "[\"I-539\",\"I-765\"]",
        "content_hash": "sha256:example",
        "doc_type": null,
        "effective_date": null,
        "comments_close_on": null
      }
    ],
    "next_cursor": "string"
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `get_fee` (sign-in required)

Returns a published government fee and its effective date. For US (the default), the general filing fee for a USCIS form and filing method. I-129, I-131, and I-907 have no general filing fee: pass category. For I-131, the label this tool uses: a short name of the Appendix B heading, a colon, and the item selector, such as "Reentry Permit: Part 1., Item Number 1." For I-129 and I-907, the category argument says how to name the classification. US covers I-90, I-130, I-140, I-485, I-539, I-765, and N-400, paper and online, and I-129, I-131, and I-907 by category; only some G-1055 categories are covered, and an uncovered one returns no fee. An I-129 amount is the filing fee G-1055 lists for that row. Fees G-1055 lists apart from it are not in the amount. An I-907 amount is the premium processing fee only, not the fee for the form it accompanies. Any other form returns not_found. For GB, the fee for a published Home Office fee category; pass the section heading as category when the name appears in more than one section. For AU, a visa application charge component that Migration Regulations 1994, Schedule 1 states for a visa subclass, from the item's table for any other applicant or its only charge table. Pass the subclass as form, such as "189", and the component as category, such as "Base application charge"; category is required when the subclass has more than one component. 500 and 590 are subclasses whose charge Schedule 1 states in item 1222. Other amounts apply to some applicants; notes names the item and compilation. amount_cents is in the minor unit of currency. filing is "unspecified" when the source states no filing channel. It does not say which fee applies to a case. For a USCIS form's current edition, use check_form_edition. Requires sign-in at https://immigrationlayer.com/login and an active plan. Without a plan it returns subscription_required. Limit: 30 calls per minute per account, shared by all paid tools, then rate_limited. Not legal advice. Sources: for US, the USCIS fee schedule (Form G-1055), the 2024 USCIS fee rule (89 FR 6194), and, for I-907, the 2026 premium processing fee rule (91 FR 1059); for GB, the Home Office visa regulations revised table on gov.uk, used under the Open Government Licence v3.0; for AU, Migration Regulations 1994, Schedule 1. Australian charges are based on content from the Federal Register of Legislation, CC BY 4.0.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `US \| GB \| AU` | No | ISO 3166-1 alpha-2 country code. "US" (default), "GB", or "AU". |
| `form` | `string` | Yes | For US, the USCIS form number exactly as USCIS writes it, e.g. "I-765"; "i765" and "I765" do not match. For GB, the published Home Office fee category name. For AU, the three-digit visa subclass, such as "500". |
| `filing` | `paper \| online` | No | How the form is filed: "paper" (mailed) or "online" (USCIS online account). Required for US. Ignored for GB and AU. |
| `category` | `string` | No | For US I-131, a short name of the Appendix B heading, a colon, and the item selector, such as "Reentry Permit: Part 1., Item Number 1." For US I-129, the classification label exactly as G-1055 Appendix A prints it, such as "If you are filing H-1B or H-1B1 petitions."; for a small employer row, that label, a space, and "If you are filing as a Small Employer or Nonprofit." For US I-907, the classification label exactly as G-1055 prints it, such as "H-2B or R nonimmigrant classification". Required for I-129, I-131, and I-907. For GB, the published section heading. Required when the fee category name appears in more than one section. For AU, the charge component exactly as the item states it, such as "Base application charge"; required when the subclass has more than one. |

```
get_fee({ form: "I-765", filing: "online" })
```

```json
{
  "data": {
    "form": "I-765",
    "filing": "online",
    "category": null,
    "amount_cents": 47000,
    "effective_date": "2024-04-01",
    "currency": "USD"
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `get_processing_time` (sign-in required)

Returns a published processing time for one form or visa route, category, and office. For US (the default), the USCIS processing-time estimate: the time within which 80% of cases were completed, in months, weeks, or days. Use it when the user asks for USCIS's published processing time for a form. It reports past completions, not how long a given case will take. Pass form, category, and office exactly as the USCIS processing times tool lists them. Every US estimate on file has both a category and an office, so omitting either returns not_found. For GB, UK Visas and Immigration's published processing time for a visa route, as the page words it. Pass the route as form, such as "Skilled Worker", and office "inside the UK" or "outside the UK". Pass the page's section heading as category when the route appears in more than one section. A time the page marks with "*" carries the page's footnote in category_notes. It does not say how long a given application will take. For AU, the "90% processed in" figure the Department of Home Affairs global visa processing times page publishes for a visa subclass and stream, as the page words it. The page bases it on recently decided applications. Pass the three-digit subclass as form, such as "500", and the stream as the page lists it as category; category is required when the subclass has more than one stream. Omit office. category_notes carries the page's caveat and any note the page gives for that subclass and stream. It does not say how long a given application will take. For Visa Bulletin waits, use get_visa_bulletin. Requires sign-in at https://immigrationlayer.com/login and an active plan. Without a plan it returns subscription_required. Limit: 30 calls per minute per account, shared by all paid tools, then rate_limited. Not legal advice. Source: for US, the USCIS processing times tool (egov.uscis.gov); for GB, the UK Visas and Immigration visa processing times pages on gov.uk for applications inside and outside the UK; for AU, the Department of Home Affairs global visa processing times page (immi.homeaffairs.gov.au). UK processing-time data contains public sector information licensed under the Open Government Licence v3.0. Australian processing-time data: Australian Government Department of Home Affairs, licensed under CC BY 3.0 AU (https://creativecommons.org/licenses/by/3.0/au/). ImmigrationLayer extracted and reformatted it.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `US \| GB \| AU` | No | ISO 3166-1 alpha-2 country code. "US" (default), "GB", or "AU". |
| `form` | `string` | Yes | For US, the USCIS form number exactly as USCIS writes it, e.g. "I-765"; "i765" and "I765" do not match. For GB, the visa route exactly as the UKVI page lists it, e.g. "Skilled Worker". For AU, the three-digit visa subclass, such as "500". |
| `category` | `string` | No | For US, the eligibility category exactly as the USCIS processing times tool lists it, e.g. "Based on an approved asylum application [(a)(5)]" for I-765. For GB, the page's section heading, such as "Popular work visas"; required when the route appears in more than one section. For AU, the visa stream exactly as the page lists it, such as "Higher Education Sector"; required when the subclass has more than one stream. |
| `office` | `string` | No | For US, the USCIS office exactly as the processing times tool lists it, e.g. "Service Center Operations (SCOPS)", "National Benefits Center", or a field office such as "Houston TX". For GB, "inside the UK" or "outside the UK". Required for GB. Omit for AU. |

```
get_processing_time({ form: "I-765", category: "Based on an approved asylum application [(a)(5)]", office: "Service Center Operations (SCOPS)" })
```

```json
{
  "data": {
    "form": "I-765",
    "category": null,
    "office": null,
    "basis": "80% of cases completed within",
    "value": 4.5,
    "unit": "Months",
    "category_notes": null
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `get_visa_bulletin` (sign-in required)

Returns one family- or employment-based cutoff from a month's State Department Visa Bulletin: the Final Action Date or Date for Filing for a preference category and chargeability country. Use it when the user asks whether a priority date is current. date_or_status is a YYYY-MM-DD cutoff, "C" (current), or "U" (unavailable). For Diversity Visa lottery cutoffs, use get_visa_bulletin_dv. For the bulletin's advisory notes on future movement, use get_visa_bulletin_notes. A month or combination not on file returns not_found. Requires sign-in at https://immigrationlayer.com/login and an active plan. Without a plan it returns subscription_required. Limit: 30 calls per minute per account, shared by all paid tools, then rate_limited. Not legal advice. Source: the Department of State Visa Bulletin (travel.state.gov).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | `string` | Yes | Bulletin month as YYYY-MM, e.g. "2026-10". A month not yet published or loaded returns not_found |
| `chart` | `final_action \| dates_for_filing` | Yes | "final_action" for the Final Action Dates chart, "dates_for_filing" for the Dates for Filing chart |
| `category` | `string` | Yes | Preference category code, exact: F1, F2A, F2B, F3, F4, EB-1, EB-2, EB-3, EB-3-OW (other workers), EB-4, EB-4-R (religious workers), EB-5 (unreserved), EB-5-RURAL, EB-5-HUA (high unemployment), or EB-5-INFRA |
| `country` | `string` | Yes | Chargeability country, exact: "China" (mainland-born), "India", "Mexico", "Philippines", or "All Chargeability Areas", the bulletin column for countries without their own column |

```
get_visa_bulletin({ month: "2026-10", chart: "final_action", category: "F2A", country: "India" })
```

```json
{
  "data": {
    "month": "2026-10",
    "chart": "final_action",
    "category": "F2A",
    "country": "India",
    "date_or_status": "2021-01-01"
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `search_alerts` (sign-in required)

Searches published immigration announcements by keyword, newest first. For US (the default), USCIS newsroom alerts and Federal Register notices. Use it to find announcements about a form or topic, e.g. "I-765" or "fee". For GB, Home Office media statements and fact sheets that the Home Office in the media feed tags as immigration, matched by title. They are statements, not rule changes. GB results cover recent posts ImmigrationLayer has stored from the feed, not a full archive. Each GB item carries its feed categories and a licence attribution. Australian alerts list registered compilations of the Migration Regulations 1994, based on content from the Federal Register of Legislation, CC BY 4.0. AU titles state only the compilation number; search "compilation" to list them. Each AU item carries its start date and a licence attribution. To list everything published since a date without a keyword, use list_form_changes, which is free. Returns at most 100 matches per page. Pass next_cursor as cursor to continue until next_cursor is null. No match returns an empty list, not an error. Requires sign-in at https://immigrationlayer.com/login and an active plan. Without a plan it returns subscription_required. Limit: 30 calls per minute per account, shared by all paid tools, then rate_limited. Not legal advice. Sources: for US, USCIS newsroom alerts and Federal Register notices; for GB, the Home Office in the media blog feed (homeofficemedia.blog.gov.uk); for AU, the Federal Register of Legislation (legislation.gov.au). UK alert data contains public sector information licensed under the Open Government Licence v3.0. The top-level source URL identifies the exact aggregate query, including the page cursor; each result preserves its government URL, source, and content hash.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `US \| GB \| AU` | No | ISO 3166-1 alpha-2 country code. "US" (default), "GB" or "AU". |
| `query` | `string` | Yes | Keyword matched case-insensitively anywhere in an alert's title. A form number such as "I-765" also matches alerts tagged with that form. Summaries are not searched |
| `since` | `string` | No | ISO 8601 date or date-time, e.g. "2026-08-01" or "2026-08-01T09:30:00Z"; limits results to alerts published on or after this instant. A date means midnight UTC; a date-time without an offset is UTC. |
| `cursor` | `string` | No | Opaque navigation cursor from the preceding page's next_cursor. Omit for the first page. |

```
search_alerts({ query: "I-765" })
```

```json
{
  "data": {
    "alerts": [
      {
        "id": "alert_123",
        "published_at": "2026-08-14T00:00:00Z",
        "title": "USCIS to publish new editions of Form I-539 and Form I-765",
        "url": "https://www.uscis.gov/newsroom/alerts/example",
        "source": "uscis_newsroom",
        "summary": null,
        "forms_json": "[\"I-539\",\"I-765\"]",
        "content_hash": "sha256:example",
        "categories": [
          "string"
        ]
      }
    ],
    "next_cursor": "string"
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `get_visa_bulletin_dv`

Returns the Diversity Visa (DV lottery) rank cutoff for one region in a month's Visa Bulletin, or a country exception the bulletin lists within that region. Use it when a DV selectee asks whether their case number is current. For family and employment chart dates, use get_visa_bulletin. For the bulletin's advisory notes, use get_visa_bulletin_notes. A month or region not on file returns not_found. Free, no sign-in required. Limit: 20 calls per minute per IP, then rate_limited. Not legal advice. Source: the Department of State Visa Bulletin (travel.state.gov).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | `string` | Yes | Bulletin month as YYYY-MM, e.g. "2026-10". A month not yet published or loaded returns not_found |
| `region` | `string` | Yes | DV region, exact: "Africa", "Asia", "Europe", "North America", "Oceania", or "South America and the Caribbean" |
| `country` | `string` | No | Chargeability country within the region; falls back to the region's "All" rate when the country has no listed exception, or when omitted |

```
get_visa_bulletin_dv({ month: "2026-10", region: "Africa", country: "Egypt" })
```

```json
{
  "data": {
    "month": "2026-10",
    "region": "Africa",
    "country": "All",
    "cutoff_or_status": "35000"
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

### `get_visa_bulletin_notes`

Returns every lettered advisory note in a month's Visa Bulletin: the forward-looking text, e.g. "EB-1 India may become unavailable". Use it when the user asks whether dates are expected to advance, hold, or retrogress. For the chart dates themselves, use get_visa_bulletin or get_visa_bulletin_dv. An empty list means the month was loaded and had no notes; a month not on file returns not_found. Free, no sign-in required. Limit: 20 calls per minute per IP, then rate_limited. Not legal advice. Source: the Department of State Visa Bulletin (travel.state.gov).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | `string` | Yes | Bulletin month as YYYY-MM, e.g. "2026-10". A month not yet published or loaded returns not_found |

```
get_visa_bulletin_notes({ month: "2026-10" })
```

```json
{
  "data": {
    "notes": [
      {
        "section": "E",
        "heading": "EB-1 India may become unavailable",
        "body": "As a result of continued high demand..."
      }
    ]
  },
  "as_of": "2026-09-15T00:00:00Z",
  "source_url": "https://www.uscis.gov/i-765",
  "content_hash": "sha256:example",
  "not_legal_advice": true
}
```

## Auth

`check_form_edition`, `list_form_changes`, `get_visa_bulletin_dv`, and `get_visa_bulletin_notes` need no sign-in. Every other tool needs a caller
identity: MCP clients (Claude, Claude Code, ChatGPT, VS Code) use OAuth with Client ID Metadata
Documents. Cursor and scripts reach the four free tools only.

## Rate limits

20 calls per minute per IP for the four sign-in-free tools and the changes resource. Paid tools share one cap: 30 calls per minute per signed-in account.

## Errors

Every answer that returns data carries as_of, source_url, content_hash, and not_legal_advice. An error has no source, so it carries none of the three citation fields, and it never repeats your arguments. A tool error sets isError and carries structuredContent with error, a message that ends with "Not legal advice.", plus reason and not_legal_advice. The reason is one of rate_limited, subscription_required, not_found, internal. An MCP call with invalid arguments gets the protocol's own tool error: a text message with no reason.

## Versioning

MCP 2026-07-28 requests include protocol version and client capabilities in each request's
`_meta`, with matching HTTP headers. The compatibility curl request is retained for older clients.
A tool's name and required arguments won't change without a new tool name; optional arguments
may be added.

## Changelog

https://immigrationlayer.com/changes.rss and https://immigrationlayer.com/changes.json

## Related

- [Home](https://immigrationcontext.com/index.md)
- [immigrationlayer.com](https://immigrationlayer.com/llms.txt): tools, connect instructions, pricing, FAQ
- [visacontext.com](https://visacontext.com/llms.txt): Visa Bulletin