Model Context Protocol (MCP)

PSGC MCP Developer Documentation

Connect your local LLMs and AI coding assistants (like Claude Desktop, Cursor, or GitHub Copilot) directly to the Philippine Standard Geographic Code (PSGC) database. Query regions, provinces, cities, municipalities, and barangays in real time.

MCP Endpoint: https://psgc.cloud/mcp

AI Client Configuration Guides

Choose your favorite AI coding tool below and configure it to use our high-fidelity MCP server.

Claude Desktop

Global AI context configuration

Add this to your global `claude_desktop_config.json` file (located under `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

{
  "mcpServers": {
    "psgc-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "https://psgc.cloud/mcp"
      ]
    }
  }
}

Cursor IDE

In-editor MCP server registration

Follow these steps inside your Cursor settings:

  1. Go to Settings > Features > MCP.
  2. Click + Add New MCP Server.
  3. Set Name: psgc-cloud
  4. Set Type: SSE (Server-Sent Events)
  5. Set URL: https://psgc.cloud/mcp
Name: psgc-cloud
Type: SSE
URL: https://psgc.cloud/mcp

Antigravity IDE

MCP config file configuration

Add this object to your `mcp_config.json` file inside your Antigravity config directory:

"psgc": {
  "serverUrl": "https://psgc.cloud/mcp",
  "headers": {
    "Accept": "application/json"
  },
  "disabledTools": [],
  "disabled": false
}

VS Code (Cline / Roo-Code)

Extension-based MCP server settings

Add this to your `cline_mcp_settings.json` file (under `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`):

"psgc-cloud": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-http",
    "https://psgc.cloud/mcp"
  ]
}

Available MCP Tools

Once connected, the AI can call the following tools dynamically. You do not need to manually parse parameters.

list_regions

List all geographic regions in the Philippines, including their PSGC codes and names.

Arguments: None
Example Payload: []
get_region

Get detailed information about a specific region by its code or name, including counts of provinces, cities/municipalities, and barangays.

Arguments: code_or_name (string, required): PSGC code or region name
Example Payload: { "code_or_name": "010000000" }
list_provinces

List all provinces in the Philippines, optionally filtered by region code or name.

Arguments: region_code_or_name (string, optional): Region code or name
Example Payload: { "region_code_or_name": "Region I" }
get_province

Get detailed information about a specific province by its code or name, including parent region and counts of cities/municipalities and barangays.

Arguments: code_or_name (string, required): PSGC code or province name
Example Payload: { "code_or_name": "Ilocos Norte" }
list_cities_municipalities

List cities and municipalities in the Philippines, optionally filtered by region, province, or type.

Arguments: region_code_or_name (string, optional), province_code_or_name (string, optional), type (string, optional: "City"|"Mun"|"SubMun")
Example Payload: { "province_code_or_name": "Albay", "type": "City" }
get_city_municipality

Get detailed information about a specific city or municipality by its code or name, including type, zip code, and count of barangays.

Arguments: code_or_name (string, required): PSGC code or city/municipality name
Example Payload: { "code_or_name": "Adams" }
list_barangays

List barangays in the Philippines, optionally filtered by region, province, or city/municipality. Limited to 250 items to prevent context overflows.

Arguments: region_code_or_name (string, optional), province_code_or_name (string, optional), city_municipality_code_or_name (string, optional)
Example Payload: { "city_municipality_code_or_name": "Adams" }
get_barangay

Get detailed information about a specific barangay by its code or name, including full ancestry (region, province, city/municipality).

Arguments: code_or_name (string, required): PSGC code or barangay name
Example Payload: { "code_or_name": "Adams (Pob.)" }
read_api_docs

Read developer documentation explaining how the REST API, hierarchy schemas, and database caching work.

Arguments: None
Example Payload: []

Local Testing & MCP Inspector

You can verify that the MCP server is working properly and inspect tool returns locally using the Laravel MCP CLI tool. Run the following command in your terminal to start the interactive web-based inspector: 

php artisan mcp:inspector psgc-cloud