FIRMSapi MCP

An official MCP server provided by FIRMSapi that allows AI agents to search, look up, and validate U.S. CBP FIRMS facility codes. It wraps REST endpoints for facility details, search, proximity, and validation, using the same API key and quotas as the standard API.

Visit FIRMSapi

Endpoint and access

No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.

Vendor evidenceStreamable HTTPNo sign-inEndpoint checked 2026-11-01Operated by FIRMSapi

You need:Get an API key: sign up at https://app.firmsapi.com/signup?plan=freeKeys come from the developer portalTest first: a fapi_test_… key returns fixture data and is never counted

MCP endpoint (Streamable HTTP)

https://api.firmsapi.com/mcp

Vendor documentation

What you can do with it

Look up a specific FIRMS code record
Search for facilities by name or address
Validate a code against a port and use
List CBP ports and their facilities

Source and maintenance

Vendor evidenceRegistry 1.0.0

mcp-registry: com.firmsapi/mcp@1.0.0 Project website

Protocol and capabilities

Server: firmsapi 1.0.0
MCP protocol: 2025-06-18
Tools: 6 advertised
Resources: Not advertised
Resource templates: Not advertised
Prompts: Not advertised

Server-advertised capabilities

{
  "tools": {
    "listChanged": false
  }
}

Server-provided instructions

Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.

FIRMSapi answers questions about U.S. CBP FIRMS codes, the 4-character facility codes for piers, container freight stations, bonded warehouses, foreign trade zones and exam sites, from the published CBP FIRMS code list. Every result carries meta.data_as_of (the date of that list) and meta.mode. Each tool call is one FIRMSapi API call and counts toward the API key's monthly plan exactly like the REST endpoint it wraps; invalid arguments, auth errors, quota errors (quota_exceeded) and server errors are not counted. Test keys (fapi_test_...) return a small fixture sample, are never counted and must not be used for filing. FIRMSapi has no connection to ACE: it does not file or check entries, and a passing validation is not ACE acceptance, so tell the user to confirm the code, bond status and port eligibility in ACE. Webhooks and change notifications are not available. Codes are four letters or digits and about a third are not a letter plus three digits, so never reject a code for its shape.

Tools

6 advertised

lookup_firms_code — Look up a FIRMS code

Advertised by the server during the last successful anonymous check.

Advertised read-only

Get the CBP FIRMS record for one code: facility name, status (active or deleted), facility type, address, CBP port, location, and the other codes registered at the same address. Deleted codes and "DO NOT USE" placeholders (junk: true) are returned with warnings. A code that is not on the list returns a not_found error, which still counts as a call. Wraps GET /v1/firms/{code}. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

lookup_firms_code input schema

{
  "type": "object",
  "required": [
    "code"
  ],
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "4-character FIRMS code, e.g. E430."
    }
  },
  "additionalProperties": false
}

lookup_firms_code annotations

{
  "title": "Look up a FIRMS code",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

search_firms_facilities — Search facilities by name or address

Advertised by the server during the last successful anonymous check.

Advertised read-only

Find FIRMS codes from a facility name and/or street address, e.g. 'maher terminal elizabeth' or '231 tyler st newark'. Typo-tolerant; returns ranked matches with a 0-100 score. Active codes only unless include_deleted is true. One call per search, however many results. Wraps GET /v1/search. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

search_firms_facilities input schema

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "port": {
      "type": "string",
      "pattern": "^[0-9]{4}$",
      "description": "4-digit CBP port code, e.g. 4601."
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "description": "Most matches to return."
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "minLength": 2,
      "description": "Name and/or address."
    },
    "state": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "2-letter state, e.g. NJ."
    },
    "types": {
      "type": "array",
      "items": {
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ],
        "type": "string"
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    }
  },
  "additionalProperties": false
}

search_firms_facilities annotations

{
  "title": "Search facilities by name or address",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

find_nearby_firms_facilities — Find facilities near a point, code or address

Advertised by the server during the last successful anonymous check.

Advertised read-only

List FIRMS facilities within radius_km, nearest first. Pass exactly one origin: lat and lon; code (another FIRMS facility, left out of the results); or address (a US street address, geocoded unless it is a FIRMS facility's own address). meta.origin says which point was used. Facilities whose address could not be geocoded are not included. Test keys use approximate coordinates. Wraps GET /v1/nearby. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

find_nearby_firms_facilities input schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "maximum": 90,
      "minimum": -90,
      "description": "Origin latitude in decimal degrees, e.g. 40.68. Pass with lon."
    },
    "lon": {
      "type": "number",
      "maximum": 180,
      "minimum": -180,
      "description": "Origin longitude in decimal degrees, e.g. -74.15. Pass with lat."
    },
    "code": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "Search around this FIRMS code."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Most facilities to return."
    },
    "types": {
      "type": "array",
      "items": {
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ],
        "type": "string"
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "address": {
      "type": "string",
      "maxLength": 200,
      "minLength": 3,
      "description": "Search around this US street address, e.g. 231 Tyler St, Newark, NJ 07114."
    },
    "radius_km": {
      "type": "number",
      "default": 10,
      "maximum": 100,
      "description": "Search radius in km around the origin.",
      "exclusiveMinimum": 0
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    }
  },
  "additionalProperties": false
}

find_nearby_firms_facilities annotations

{
  "title": "Find facilities near a point, code or address",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

validate_firms_code — Check a FIRMS code before filing

Advertised by the server during the last successful anonymous check.

Advertised read-only

Pre-filing checks of a FIRMS code against the published CBP list, in order: format, exists (catches ACE reject 158), active (159), in the stated port (164), facility type fits the use (warehouse_entry: bonded warehouse 04; ftz_admission: FTZ 02; exam_site: CES 09; location_of_goods: not 07 or 08), not a placeholder. Returns valid, checks_passed, checks_failed, checks_skipped, checks_not_possible (bond status, FTZ zone ID, direct delivery, port clusters: not in the FIRMS list) and a note. valid: true is not ACE acceptance: FIRMSapi has no ACE connection, so confirm in ACE before filing. A failing code is a normal result (valid: false) and counts as a call. Wraps POST /v1/validate. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

validate_firms_code input schema

{
  "type": "object",
  "required": [
    "code"
  ],
  "properties": {
    "use": {
      "enum": [
        "warehouse_entry",
        "ftz_admission",
        "exam_site",
        "location_of_goods"
      ],
      "type": "string",
      "description": "How the code will be used; enables the facility type check."
    },
    "code": {
      "type": "string",
      "maxLength": 32,
      "minLength": 1,
      "description": "The code as it appears in your system. A malformed code is a failed check."
    },
    "port": {
      "type": "string",
      "maxLength": 8,
      "description": "4-digit CBP port of entry of the filing."
    }
  },
  "additionalProperties": false
}

validate_firms_code annotations

{
  "title": "Check a FIRMS code before filing",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

list_cbp_ports — List CBP ports

Advertised by the server during the last successful anonymous check.

Advertised read-only

Every CBP port that has FIRMS codes, with name, state, region, facility_count and active_count, in one call. Wraps GET /v1/ports. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

list_cbp_ports input schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_cbp_ports annotations

{
  "title": "List CBP ports",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

get_cbp_port — Get a CBP port and its facilities

Advertised by the server during the last successful anonymous check.

Advertised read-only

One CBP port with a page of its FIRMS facilities, ordered by code. Placeholders are left out; active codes only unless include_deleted is true. For the next page pass cursor = meta.next_cursor (null on the last page); each page is one call. Wraps GET /v1/ports/{port}. Live keys (fapi_live_...): one counted call. Test keys (fapi_test_...): fixture sample data, not counted.

get_cbp_port input schema

{
  "type": "object",
  "required": [
    "port"
  ],
  "properties": {
    "port": {
      "type": "string",
      "pattern": "^[0-9]{4}$",
      "description": "4-digit CBP port code, e.g. 4601."
    },
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Facilities per page."
    },
    "types": {
      "type": "array",
      "items": {
        "enum": [
          "01",
          "02",
          "03",
          "04",
          "05",
          "06",
          "07",
          "08",
          "09",
          "10",
          "11"
        ],
        "type": "string"
      },
      "description": "Only these facility types: 01 Container freight station (CFS), 02 Foreign trade zone (FTZ), 03 Pier or terminal, 04 Bonded warehouse, 05 Inspection facility, 06 Importer premises, 07 DP site, 08 CBP administrative, 09 Centralized examination station (CES), 10 Rail or air terminal (inferred), 11 CBP test."
    },
    "cursor": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{4}$",
      "description": "meta.next_cursor from the previous page."
    },
    "include_deleted": {
      "type": "boolean",
      "default": false,
      "description": "Include deleted codes (ranked after active ones)."
    }
  },
  "additionalProperties": false
}

get_cbp_port annotations

{
  "title": "Get a CBP port and its facilities",
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

Prompts

Not advertised

No prompt definitions available.

Resources

Not advertised

No resource definitions available.

30-day availability

Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.

Successful checks: 1 of 1 (100%)
Average latency: 548 ms
95th percentile latency: 548 ms

Maintenance history

Public check and source-refresh events. Editorial and ownership records remain private.

Nov 1, 2026, 6:56 AM UTC · probe · passed · 548 ms · metadata changed · 6 tool(s)

Connect from your client

Each snippet registers the same endpoint; pick the client you use.

This server is operated by the named third party. Listing and endpoint checks are not an endorsement or a security audit. Review the operator's permissions, terms, and data handling before connecting. How listings are checked and corrected.

Claude Code

Run this once in a terminal. It registers the remote server. Use --scope project to write .mcp.json for the repo.

Claude Code configuration

claude mcp add --transport http firmsapi-mcp https://api.firmsapi.com/mcp

Codex

Run this once. Codex stores MCP servers in ~/.codex/config.toml (or .codex/config.toml in a trusted project).

Codex configuration

codex mcp add firmsapi-mcp --url https://api.firmsapi.com/mcp

Cursor

Merge this server into .cursor/mcp.json in your project, then enable firmsapi-mcp in your MCP settings.

Cursor configuration

{
  "mcpServers": {
    "firmsapi-mcp": {
      "url": "https://api.firmsapi.com/mcp"
    }
  }
}

Cline

Merge this into cline_mcp_settings.json (Cline → MCP Servers → Configure).

Cline configuration

{
  "mcpServers": {
    "firmsapi-mcp": {
      "type": "streamableHttp",
      "url": "https://api.firmsapi.com/mcp",
      "disabled": false
    }
  }
}

VS Code

Merge this server into .vscode/mcp.json. Use MCP: List Servers to start firmsapi-mcp and inspect its tools.

VS Code configuration

{
  "servers": {
    "firmsapi-mcp": {
      "type": "http",
      "url": "https://api.firmsapi.com/mcp"
    }
  }
}

Gemini CLI

Run this once. It writes .gemini/settings.json in the current project; pass --scope user for ~/.gemini/settings.json.

Gemini CLI configuration

gemini mcp add --transport http firmsapi-mcp https://api.firmsapi.com/mcp

Claude Desktop

Merge this into claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop.

Claude Desktop configuration

{
  "mcpServers": {
    "firmsapi-mcp": {
      "url": "https://api.firmsapi.com/mcp"
    }
  }
}

Windsurf

Merge this into ~/.codeium/windsurf/mcp_config.json, then refresh MCP in Cascade. Windsurf remote servers use serverUrl, not url.

Windsurf configuration

{
  "mcpServers": {
    "firmsapi-mcp": {
      "serverUrl": "https://api.firmsapi.com/mcp"
    }
  }
}

Let your agent find its tools

Find servers like FIRMSapi MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.

Connect Koskamo Explore workflows

See all 4,067

Do you run FIRMSapi MCP?

Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.

Claim this listing

FIRMSapi MCP

Endpoint and access

What you can do with it

Source and maintenance

Protocol and capabilities

Server-provided instructions

Tools

Prompts

Resources

30-day availability

Maintenance history

Connect from your client

Claude Code

Codex

Cursor

Cline

VS Code

Gemini CLI

Claude Desktop

Windsurf

Let your agent find its tools

Other data and analytics servers

Do you run FIRMSapi MCP?