MCP Server: Connecting AI Agents to Brazilian National, State, and Municipal Holidays

Artificial intelligence is transforming how we build software, but it still struggles with a fundamental limitation: lack of real-time, hyperlocal context. If you ask Claude, Cursor, or GPT whether tomorrow is a holiday in Campinas or São Paulo, the answer is usually a guess or a generic hallucination. With the Model Context Protocol (MCP), that has changed forever.

The Model Context Protocol is an open standard introduced by Anthropic that enables Large Language Models (LLMs) to securely access data sources, execute tools, and read external resources. Instead of forcing AI models to guess regional calendars or rely on fragile web scraping, the Feriados MCP Server directly exposes accurate Brazilian national, state, and municipal holidays to your autonomous AI agents.

In this technical guide, we explore how this breakthrough architecture works, why hyperlocal calendar context is vital for enterprise apps in Brazil, and how to configure the holidays server in Claude Desktop, Cursor IDE, or Windsurf in under two minutes.

Model Context Protocol: The Missing Bridge Between LLMs and APIs

Previously, connecting external REST APIs to an LLM required building complex custom orchestration pipelines or middlewares using frameworks like LangChain or Semantic Kernel. Every tool definition, error handler, and schema serialization had to be hardcoded and maintained manually.

MCP standardizes this client-server communication for AI environments:

How MCP works: the AI dynamically discovers and executes holiday validation tools during reasoning.

When you attach the Feriados MCP Server to your AI workspace (such as Cursor, Windsurf, or Claude Desktop), your LLM instantly gains the ability to query FEBRABAN banking holidays, state celebrations, and municipal holidays across all 5,570 Brazilian municipalities autonomously—without writing a single line of boilerplate integration code.

Tools Exposed by the Feriados MCP Server

The Feriados MCP Server acts as an intelligent toolkit, providing structured functions that the LLM can invoke whenever it detects date-sensitive scheduling:

• 🔍buscar_feriados:Allows the AI to query national, state, or municipal holidays for a specific year or IBGE municipality code (Brazil's official 7-digit geographic city identifier, equivalent to US FIPS codes).
• 🏦verificar_dia_util_bancario: Verifies if a specific financial transaction falls on a valid FEBRABAN banking settlement business day.
• 📅verificar_data: Instantly validates whether a date proposed by a user is a working day or a holiday in their specific city or state.

Step-by-Step Setup in Claude Desktop & Cursor IDE

Connecting the Brazilian holidays server to your AI development workflow takes less than two minutes using npm.

1. Claude Desktop Configuration

Open your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following server block:

{
  "mcpServers": {
    "feriadosapi": {
      "command": "npx",
      "args": ["-y", "@feriadosapi/mcp-server"],
      "env": {
        "FERIADOS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

2. Cursor IDE Configuration

In Cursor, navigate to Settings > Features > MCP. Click + Add New MCP Server and fill in the parameters:

• Name: Feriados API
• Type: command
• Command: npx -y @feriadosapi/mcp-server
• Env Variables: Add key FERIADOS_API_KEY with your free API token from our dashboard.

Once saved, Cursor will show a green status indicator confirming the connection. Your AI assistant will now seamlessly use Brazilian holiday intelligence during code refactoring, system design, or chatbot interactions.

Conclusion: The Future of Autonomous Agent Development

The Model Context Protocol eliminates the friction of integrating specialized data into global language models. The Feriados MCP Server demonstrates how enterprise software can empower AI with accurate, compliance-ready regional intelligence across Brazil.

Ready to upgrade your AI agents? Create your free account on Feriados API and add the MCP Server to your workflow today!