MCP server for the Philippine Standard Geographic Code (PSGC) API. Gives AI agents structured access to the full PH geographic hierarchy - regions, provinces, cities, municipalities, and barangays.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.1/5 across 7 of 7 tools scored.
Each tool has a clearly distinct purpose: lookup single code, batch lookup, search by name, list by geographic level, list children, get hierarchy, and query by population. There is no overlap; even the two lookup tools are differentiated by batch vs single.
Most tools follow a verb_noun pattern in snake_case (e.g., batch_lookup, get_hierarchy, list_children), but 'lookup' and 'search' are single words, and 'list_by_type' and 'query_by_population' include prepositions. The naming is clear and readable but not perfectly uniform.
7 tools is well-scoped for a geographic entity server. Each tool provides a distinct function without being too few (covering essential lookups, search, and listing) or too many (no redundancy).
The tool set covers all common read operations for geographic entities: single and batch lookup, name search, listing by type and children, hierarchy, and population queries. There are no obvious gaps for the intended read-only domain.
batch_lookupAInspectLook up multiple PSGC entities in one call. Pass an array of 10-digit codes (max 50). Returns results in the same order as input, with null for codes not found.
| Name | Required | Description | Default |
|---|---|---|---|
| codes | Yes | Array of 10-digit PSGC codes (1-50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses two critical behaviors: results are returned in the same order as input, and codes not found yield null. The max-50 limit is also stated. These go beyond basic schema information and are highly useful for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose and followed by input/output specifics. Every sentence is necessary and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description adequately explains the purpose, input constraints, and return behavior (order and null handling). It is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of the single parameter, including pattern, length, and description. The description adds little new semantic meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Look up' with the resource 'PSGC entities', and explicitly differentiates from siblings by emphasizing 'multiple' and 'in one call'. This clearly distinguishes it from the likely single-entity 'lookup' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: pass an array of codes and receive ordered results with nulls for missing codes. It implies the tool is for batch operations but does not explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_hierarchyAInspectGet the full administrative hierarchy for a PSGC entity. Returns the chain from the entity up through its parent city/municipality, province, and region.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 10-digit PSGC code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly states the traversal direction (up through parents) and the components of the hierarchy (city/municipality, province, region), providing meaningful behavioral context. Minor gaps remain (e.g., handling of top-level entities, whether the entity itself is included), but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the verb and resource, and contains no filler. Every word adds value, clearly explaining both the action and the return structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and no output schema. The description adequately explains the return value (the hierarchy chain) and the entity type (PSGC), giving an AI enough context to select the tool. It doesn't detail exact output formatting, but that is unlikely necessary for tool selection given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of the single parameter ('code') with a clear description ('10-digit PSGC code'). The tool description adds no additional parameter information, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Get the full administrative hierarchy') and resource ('PSGC entity'), then specifies exactly what is returned (chain up through city/municipality, province, and region). This distinguishes it from sibling tools like list_children (which likely goes downward) and lookup (which likely returns a single entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: when you need the full upward hierarchy for a PSGC code. It doesn't explicitly name sibling tools or contrast them, but the description's specificity provides enough context to infer when this tool is appropriate (vs. list_children for downward traversal or lookup for a single entity).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_by_typeAInspectList all PSGC entities of a given geographic level. Barangay (Bgy) is excluded because there are 42,000+ barangays. To find barangays, use 'search' with a name query or 'list_children' on a city/municipality. Paginated (default limit: 50).
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | Geographic level: Reg (region), Prov (province), Dist (district), City, Mun (municipality), SubMun (sub-municipality), SGU (special geographic unit) | |
| limit | No | Max records to return (default 50, max 200) | |
| offset | No | Number of records to skip (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It transparently states the Barangay exclusion and pagination (default limit 50). However, it does not mention return format or any other edge-case behavior, leaving a small gap in behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using only three sentences. It front-loads the core purpose in the first sentence, then delivers essential exclusions and guidance. Every sentence contributes meaningful information with no redundancy or bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple list tool with well-documented parameters, the description is sufficiently complete. It covers purpose, exclusions, alternatives, and pagination. While there is no output schema, the description provides enough context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for all three parameters (100% coverage). The description adds no new parameter semantics beyond reiterating the default limit, which is already documented in the schema. Thus, it meets the baseline for high schema coverage without adding extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List'), resource ('PSGC entities'), and key scope ('given geographic level'). It also distinguishes itself by explicitly excluding Barangays and pointing to sibling tools for that use case, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool versus alternatives: it notes that Barangay is excluded and directs users to 'search' or 'list_children' for barangays. It also mentions pagination details, making it easy to decide if this tool fits the user's need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_childrenAInspectList the direct children of a PSGC entity. For a region, returns provinces/districts. For a province, returns cities/municipalities. For a city/municipality, returns barangays. Optionally filter by level. Paginated (default limit: 50).
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 10-digit PSGC code of the parent entity | |
| level | No | Filter children by geographic level | |
| limit | No | Max records to return (default 50, max 200) | |
| offset | No | Number of records to skip (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses pagination (default limit 50) and the hierarchical mapping, but does not mention error behavior, return format, or edge cases like invalid codes or unsupported level filters. This leaves notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences, front-loading the primary action and hierarchy logic. Every word adds value, and it is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description should explain return values and edge cases. It covers hierarchy and pagination well, but omits the return structure and error scenarios, making it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds context about the hierarchy and confirms the default limit, but it does not significantly enrich the parameter meanings beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('direct children of a PSGC entity'), and clearly explains the hierarchy mapping for different entity types. This distinguishes it from siblings like get_hierarchy and list_by_type, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use the tool by explaining the level-by-level traversal (region to provinces/districts, etc.) and mentions optional level filtering. However, it does not explicitly mention alternatives or when not to use the tool, so it provides clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookupAInspectLook up a Philippine geographic entity by its 10-digit PSGC code. Returns the full entity record including name, level, parent, population, and classification data.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 10-digit PSGC code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool returns (full entity record with specific fields), which is useful, but it does not disclose error behavior for invalid or non-existent codes, or any other operational caveats. For a simple lookup, this is acceptable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence stating purpose and the second listing return contents. It is front-loaded, free of fluff, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, no output schema), the description is largely complete: it identifies input, purpose, and return fields. The only missing piece is potential error/edge-case behavior, but that is not critical for a straightforward lookup operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'code' with pattern and length constraints, plus a description. The tool description reinforces that the code is a Philippine PSGC code but adds no additional semantic detail beyond the schema. Since schema coverage is 100%, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Look up') and clearly identifies the resource ('Philippine geographic entity') and the key identifier (10-digit PSGC code). It distinguishes from siblings like batch_lookup and search by focusing on a single entity lookup by code and specifying the returned record contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the primary use case: when you have a 10-digit PSGC code and need the full entity record. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query_by_populationAInspectQuery PSGC entities by population range. Returns entities sorted by population. Useful for finding the largest/smallest cities, municipalities, or provinces. Barangay queries require a parent_code to narrow scope.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order by population (default: desc) | |
| level | Yes | Geographic level to query | |
| limit | No | Max results to return (default 10, max 100) | |
| offset | No | Number of records to skip (default 0) | |
| parent_code | No | Filter to entities within this parent (required for Bgy). Uses code prefix matching. | |
| max_population | No | Maximum population (inclusive) | |
| min_population | No | Minimum population (inclusive) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the sorting guarantee and the Barangay parent_code requirement, but these are also present in the schema. It doesn't mention if there are any side effects (though it's a query), nor does it explain the response structure or pagination behavior beyond what the schema already covers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each serving a distinct purpose: purpose, behavior, use case, and a key constraint. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description explains the tool's intent and key constraint but does not describe the return format or default pagination behavior. The schema covers parameter defaults, but the lack of output schema leaves a gap in understanding what fields are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 7 parameters, so the baseline is 3. The description only reinforces the parent_code requirement and the population range concept, adding little new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Query'), resource ('PSGC entities'), and scope ('by population range'). It also mentions the output behavior ('Returns entities sorted by population') and differentiates from sibling tools by focusing on population-based queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('finding the largest/smallest cities, municipalities, or provinces') and notes a prerequisite for Barangay queries (parent_code). It doesn't explicitly compare with alternatives, but provides sufficient context for when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchAInspectSearch Philippine geographic entities by name. Supports partial matching. Use the level filter to narrow results (e.g. only cities, only provinces). For barangay searches, include the parent city/municipality name to get better results.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Filter by geographic level | |
| limit | No | Max results (default 10, max 50) | |
| query | Yes | Search query (place name or partial name) | |
| strict | No | Exact name match only (no partial/substring matching) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses partial matching behavior and suggests including parent names for better barangay results, adding some behavioral insight beyond the schema. With no annotations provided, it carries the burden, but it doesn't mention return format, pagination, or whether the operation is read-only, so it's minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: purpose, partial matching + level filter, and a specific tip for barangay searches. No redundancy or superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives useful guidance for common use cases but lacks information about output format, ordering, or error behavior, which is notable since there's no output schema. It covers essential usage but isn't fully complete for an agent that needs to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds practical meaning by explaining the level filter's purpose and advising on query composition for barangay searches, which goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'searches Philippine geographic entities by name' with partial matching, giving a specific verb and resource. However, it doesn't explicitly differentiate from sibling tools like 'lookup' or 'list_by_type', so it's a clear purpose but without sibling comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: use the level filter to narrow results and include the parent city/municipality name for barangay searches. However, it doesn't mention when to use this tool versus alternatives like 'batch_lookup' or 'lookup', so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
