Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-servicos-pt Que tempo vai fazer em Lisboa amanhã?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP de serviços portugueses. Primeiro conector: IPMA (meteorologia) — API pública, sem chave, sem autenticação.
src/mcp_servicos_pt/
├── server.py # monta o servidor, regista conectores
├── __main__.py # ponto de entrada (`python -m mcp_servicos_pt`)
├── core/connector.py # contrato que cada conector cumpre
└── connectors/ipma/
├── client.py # HTTP puro, fala com api.ipma.pt — sem MCP
├── models.py # traduz a resposta bruta para JSON legível
└── connector.py # regista as tools no servidor MCPRelated MCP server: IPMA MCP Server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"pytest tests/ -vO Inspector é a ferramenta oficial para testar um servidor MCP visualmente, sem precisar de configurar o Claude Desktop.
npx @modelcontextprotocol/inspector python -m mcp_servicos_ptAbre o URL que aparece no terminal, clica em "List Tools" e devem
aparecer listar_localidades_pt e previsao_tempo_pt. Chama
listar_localidades_pt primeiro para obteres um globalIdLocal
válido, e usa-o depois em previsao_tempo_pt.
No ficheiro de configuração do Claude Desktop
(~/Library/Application Support/Claude/claude_desktop_config.json
no macOS, ou o equivalente no Windows/Linux), acrescenta:
{
"mcpServers": {
"servicos-pt": {
"command": "/caminho/completo/para/.venv/bin/python",
"args": ["-m", "mcp_servicos_pt"],
"cwd": "/caminho/completo/para/mcp-servicos-pt"
}
}
}Reinicia o Claude Desktop e pergunta algo como "que tempo vai fazer em Lisboa nos próximos dias?" — o modelo deve encadear as duas tools sozinho.
Este projeto foi construído num ambiente sem acesso de rede a
api.ipma.pt, por isso os nomes dos campos em models.py (tMin,
tMax, idWeatherType, forecastDate, ...) vêm da documentação
pública conhecida do IPMA, mas não foram confirmados com uma
chamada real. O código foi escrito de forma defensiva (usa .get()
em vez de aceder direto às chaves), por isso não deve rebentar mesmo
que um nome tenha mudado — mas antes de confiares nos valores,
corre listar_localidades_pt e previsao_tempo_pt no teu ambiente,
compara com a resposta bruta em https://api.ipma.pt/open-data/ e
ajusta models.py se algum campo não bater certo. O resto da
arquitetura não muda.
Para adicionar um segundo serviço (ex. dados.gov.pt):
Cria connectors/dados_gov/{client,models,connector}.py seguindo
exatamente o mesmo padrão do IPMA.
Regista-o em server.py:
DadosGovConnector().register(mcp)
Nada no núcleo precisa de mudar.
Lista os distritos e ilhas portugueses conhecidos pelo IPMA.
Cada entrada inclui um globalIdLocal — o identificador
necessário para pedir a previsão do tempo dessa localidade
com a tool previsao_tempo_pt.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the transparency burden. It discloses that the tool is a listing operation, enumerates the scope (districts and islands known by IPMA), and states what each returned entry contains. It does not mention ordering or limits, but these are minor for a zero-parameter read-only list tool.
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 tight sentences with no filler. The core purpose is stated first, and the cross-reference to previsao_tempo_pt adds valuable routing information without bloating the text.
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 zero-parameter list tool with an output schema, the description is fully sufficient: it states what the list contains and how its output should be consumed by the sibling tool. Nothing an agent needs to invoke it correctly is missing.
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 tool has zero parameters, so there is nothing further that parameter documentation could add. The description appropriately explains the tool's output and downstream usage without needing to describe parameter syntax.
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 ('Lista') and a clearly bounded resource: Portuguese districts and islands known by IPMA. It also directly distinguishes itself from the only sibling tool by explaining that this tool returns locality identifiers, not forecasts.
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 explicitly tells the agent why this tool is useful: each returned entry contains the globalIdLocal needed to call previsao_tempo_pt. This makes the division of labor between the two sibling tools unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Devolve a previsão diária do tempo (temperatura, chuva,
vento) para uma localidade portuguesa, identificada pelo
globalIdLocal obtido em listar_localidades_pt.
| Name | Required | Description | Default |
|---|---|---|---|
| global_id_local | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 disclosing behavior. It states that the tool returns a daily forecast with temperature, rain, and wind, which is useful. However, it does not disclose whether the forecast is for a single day, a week, or other details such as units (Celsius, mm/h, km/h) or the response shape. With no annotations, these omissions are noticeable but not critical; the description gives the essential nature of the operation. A score of 3 is fair as it covers the basic behavior but not full transparency.
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 a single, well-formed sentence in Portuguese with no waste. It front-loads the main purpose (daily forecast) and quickly specifies the scope and the parameter source. Every clause adds value. It is concise and easy to parse.
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 one required parameter, a simple output schema (though we don't see it), and no annotations. The description adequately ties to the sibling tool for parameter acquisition, which is a major piece of context. It doesn't detail the output format, but since an output schema exists (has output schema: true), the description doesn't need to explain return values. The context is complete enough for the agent to know what the tool does and how to obtain its input, though additional details like units could be useful. Given the complexity, this is reasonably 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?
Schema coverage is 0%, so the description must explain the parameter. The description mentions `globalIdLocal` in backticks and indicates it comes from `listar_localidades_pt`, which gives the source and format (an identifier). However, it does not explain what the integer represents (e.g., a locality code) or its range. Since the schema only provides the type 'integer', the description adds some value by pointing to the sibling tool, but it could provide more semantics like 'code of the locality'.
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 a specific verb ('Devolve') and resource ('previsão diária do tempo') with the key attributes (temperatura, chuva, vento) and the geographic scope ('localidade portuguesa'). It is distinct from the sibling 'listar_localidades_pt', which is a listing tool, so it differentiates well. A minor deduction because it doesn't explicitly name the sibling that it complements, but the contrast is apparent.
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 explicitly instructs the agent to obtain the required parameter `globalIdLocal` from the sibling tool `listar_localidades_pt`. This gives clear guidance on when and how to use the tool: first list locations, then fetch the forecast for a chosen local. This is a strong integration hint that eliminates ambiguity about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0listar_localidades_ptprevisao_tempo_ptScored across 2 tools
Each tool has a clearly distinct purpose: one lists available localities, and the other returns the forecast for a selected locality. The descriptions explicitly reference each other, leaving no ambiguity about when to use which.
Both names share the same '_pt' suffix and snake_case style, but one uses a verb ('listar') while the other uses a noun ('previsao') instead of a verb form like 'obter_previsao'. This is a minor inconsistency that does not hurt readability.
Two tools is minimal, but it is a reasonable size for the narrow, read-only weather forecast domain. The pair forms a clean two-step workflow with no redundant tools.
For the stated purpose of providing IPMA weather forecasts for Portuguese localities, the surface is complete: you can discover locations and retrieve the forecast. No update, delete, or write operations are relevant to this domain.
Global weather via Open-Meteo: forecast, historical, marine, air quality, geocoding, elevation.
Weather forecasts from MET Norway (Yr): geocoding plus hourly forecasts worldwide.
Geocoding, weather forecasts, and timezone lookups
Pirate Weather forecast API (Dark Sky-compatible). Free key required.