# Paraíba Open Data MCP

> Paraíba Open Data connects your AI agent directly to the State of Paraíba’s official public finance records. Use this server to audit government spending, track budget allocations (`get_dotacao`), monitor payroll costs (`get_folha_pagamento`), and analyze contracts and payments in real-time conversation.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** public-spending, transparency, budget-tracking, brazil-data, financial-auditing, open-data

## Description

This **Paraíba Open Data MCP Server** lets your agent talk directly to the State of Paraíba’s public finance records, giving you an operational audit layer, not just a dump of data. You'll run multi-step audits across the entire life cycle of government spending—from budget allocation all the way through final payments and personnel costs. 

You start by tracking how the state plans to spend money. You check allocated funds using `get_dotacao`, figure out where that cash is supposed to come from with `get_fonte_recurso`, and even predict future income streams by running `get_receitas_previsao`. To understand the full budget picture, you can pinpoint the specific budgetary unit responsible for the money via `get_unidade_orcamentaria` or narrow it down further using `get_elemento_despesa`, which classifies expenditure types.

When you need to know how much cash is actually available, your agent retrieves detailed commitment notes with `get_empenho`; this shows exactly when funds were initially reserved against the budget. For a full picture of potential liabilities, it lists outstanding payables—the money owed but not yet paid out by the government—using `get_restos_a_pagar`. You can also track which specific administrative body is running the project using `get_unidade_gestora`, or get deeper context on the spending purpose with `get_funcao` and its sub-classification, `get_subfuncao`.

The next step in any audit is confirming that the goods or services were actually received. Your agent reviews liquidation details via `get_liquidacao`, which confirms acceptance, followed by getting payment authorizations using `get_autorizacao_pagamento`. You'll see exactly what kind of government action prompted the spend with `get_acao_governamental`, and you can determine the specific department involved by calling `get_unidade_orcamentaria` again. The system helps audit expenditures across different contractual scopes; it lists core government contracts through `get_contratos`, but it also tracks any changes or additions to those original agreements using `get_contratos_aditivos`. You can view formal arrangements and covenants between state entities by calling `get_convenios`, while understanding the process requires reviewing the bidding method used, which is provided by `get_modalidade_licitacao`.

For personnel costs, you get a full summary of payroll expenses for all state employees with `get_folha_pagamento`. If you need to track travel spending, your agent pulls records for daily allowances paid to public servants using `get_diarias`. You can also check how the budget is organized by seeing what specific government functions are involved through `get_funcao` and its detailed counterpart, `get_subfuncao`.

The server lets you track all financial movements that affect resources. It pulls data showing revenue that has actually been collected and executed using `get_receitas_execucao`, providing a hard number on cash flow. You can also check the physical mechanisms of spending by retrieving details about specific government actions with `get_acao_governamental` and identifying which source of funding was used in any given transaction via `get_fonte_recurso`. This entire setup allows you to build an end-to-end financial audit trail, grouping together everything from initial budget checks (`get_dotacao`) through commitment notes (`get_empenho`), final contract management (`get_contratos`, `get_contratos_aditivos`), and payroll summaries (`get_folha_pagamento`).

## Tools

### get_acao_governamental
Retrieves specific data related to government actions.

### get_autorizacao_pagamento
Gets records detailing payment authorizations for state spending.

### get_contratos_aditivos
Retrieves records of any changes or additions made to original contracts.

### get_contratos
Lists core government contracts and their details.

### get_convenios
Fetches data on agreements and covenants between state entities.

### get_diarias
Gets records for daily allowances paid to public servants (travel expenses).

### get_dotacao
Retrieves detailed information on budget allocations.

### get_elemento_despesa
Gets classifications for specific types of expenditures.

### get_empenho
Retrieves commitment notes, showing when funds were initially reserved against a budget.

### get_folha_pagamento
Generates a summary of payroll expenses for state personnel.

### get_fonte_recurso
Gets data identifying the source of funding used in transactions.

### get_funcao
Retrieves classification data for specific government functions.

### get_liquidacao
Gets records confirming that goods or services were received and accepted (liquidation).

### get_modalidade_licitacao
Retrieves details on the bidding method used for government contracts.

### get_receitas_execucao
Gets data showing revenue that has actually been collected and executed.

### get_receitas_previsao
Retrieves forecasts for expected future state revenues.

### get_restos_a_pagar
Lists outstanding payables—money owed but not yet paid out by the government.

### get_subfuncao
Gets more granular classification data for specific sub-functions.

### get_unidade_gestora
Retrieves information about the managing or administering unit of a government project.

### get_unidade_orcamentaria
Gets data identifying the specific budgetary unit responsible for funds.

## Prompt Examples

**Prompt:** 
```
Show me the budget allocation (dotação) for Paraíba in 2024.
```

**Response:** 
```
I've retrieved the budget allocation data for 2024. The total authorized amount is distributed across various departments. Would you like a breakdown by month or by management unit?
```

**Prompt:** 
```
What was the payroll summary for March 2024?
```

**Response:** 
```
For March 2024, the payroll summary shows the total gross and net values for state employees. I can provide the specific totals for active, inactive, and pensioned personnel if needed.
```

**Prompt:** 
```
List the daily allowances (diárias) paid in January 2024.
```

**Response:** 
```
I found the records for daily allowances in January 2024. The data includes the names of recipients, the purpose of travel, and the amounts paid. Should I summarize the top spending units?
```

## Capabilities

### Track Budget Flow
Check allocated funds (`get_dotacao`), predict future revenues (`get_receitas_previsao`), and analyze resource sources (`get_fonte_recurso`) to see where the money is coming from.

### Audit Spending Lifecycle
Review commitment notes (`get_empenho`), liquidation details (`get_liquidacao`), and payment authorizations (`get_autorizacao_pagamento`) to track exactly how funds were spent.

### Manage Personnel Costs
Generate payroll summaries (`get_folha_pagamento`) and view daily allowances (`get_diarias`) to monitor state employee expenses.

### Review Agreements and Contracts
List and analyze government contracts (`get_contratos`), covenants (`get_convenios`), and addendums (`get_contratos_aditivos`) in one query.

## Use Cases

### Tracking a Single Contract's Full Cost
A legal team needs to know the total cost of a specific government agreement. They ask their agent: 'Start with `get_contratos` for Agreement X, then check all related `get_contratos_aditivos`, and finally tally up payments using `get_autorizacao_pagamento`. The agent runs these tools in sequence and gives them the total spend.' This saves hours of manual data correlation.

### Auditing a Department’s Budget Overrun
An auditor suspects a unit is spending too fast. They ask the agent to pull `get_dotacao` for that unit, then run `get_empenho` and compare it against `get_liquidacao`. The system immediately flags any commitments that haven't been liquidated yet, pinpointing the exact risk.

### Investigating Travel Spending Patterns
A journalist wants to know which regions spent the most on travel. They prompt: 'List all daily allowances (`get_diarias`) for Q1 and summarize by location.' The agent aggregates the data, showing spending units and total amounts paid instantly.

### Understanding Resource Source Changes
A researcher needs to know if a project is funded correctly. They run `get_fonte_recurso` alongside `get_unidade_orcamentaria`. The agent confirms the legal source of funding and verifies it matches the unit responsible for the budget.

## Benefits

- Pinpoint financial discrepancies by cross-referencing commitments (`get_empenho`) with actual payments (`get_autorizacao_pagamento`). You see exactly where the money moved, step-by-step.
- Stop manual payroll calculations. Use `get_folha_pagamento` to instantly get comprehensive summaries of state employee costs, segmenting by active or pensioned status.
- Avoid missing obligations: By running `get_restos_a_pagar`, you immediately identify money the government legally owes but hasn't paid out yet. It’s a critical audit check.
- Build complete financial narratives by combining contract data (`get_contratos`) with payment authorizations and covenants (`get_convenios`), creating an immutable trail of spending.
- Understand revenue fluctuations instantly. Compare historical collections using `get_receitas_execucao` against future projections from `get_receitas_previsao` to gauge financial health.

## How It Works

The bottom line is: you use natural language prompts to trigger multi-step financial queries across twenty specialized data points.

1. Subscribe to the Paraíba Open Data server on Vinkius.
2. Input your API access token for the Paraíba data proxy into your AI client settings.
3. Ask your agent a specific question, like 'What were the total payroll costs last month?' and let it run the necessary tools.

## Frequently Asked Questions

**How do I compare budget allocations with actual spending? (get_dotacao and get_empenho)**
You run `get_dotacao` first to see the authorized funds. Then, you use `get_empenho` to see what portion of that budget has been committed. The difference gives you a clear picture of available, uncommitted funds.

**What’s the difference between 'commitment' and 'payment'? (get_empenho vs get_autorizacao_pagamento)**
A commitment (`get_empenho`) reserves money; it says, 'We plan to spend this.' A payment authorization (`get_autorizacao_pagamento`) confirms the funds are actually being released. One is intent, the other is action.

**Can I track payroll costs and contracts simultaneously? (get_folha_pagamento and get_contratos)**
Yes. You can ask your agent to pull both `get_folha_pagamento` data and list relevant contracts using `get_contratos`. The agent will combine these two datasets into one report for comparison.

**How do I know if money was spent or just promised? (get_restos_a_pagar)**
`get_restos_a_pagar` shows outstanding payables—money that is owed but hasn't been paid. If this number is high, it means the state owes a lot of cash and you need to check why.

**How do I authenticate my AI client to use `get_contratos`?**
You must provide your specific API access token in the server settings. This key authenticates your agent and grants read-only access to the Paraíba data proxy.

**Can I limit results using a specific code with `get_elemento_despesa`?**
Yes, you pass the detailed expense element code directly into the tool prompt. This narrows the scope immediately, preventing massive result sets and boosting performance.

**What happens if I run a query using `get_autorizacao_pagamento` outside of business hours?**
The data reflects records available in the proxy at that moment. Always assume potential latency; critical transactions may update during standard operating hours.

**How do I combine results from `get_unidade_gestora` and `get_funcao`?**
You run both tools separately, then feed the resulting IDs into a single prompt. Your agent can cross-reference these two lists to map complete organizational units.

**Can I see the total payroll for a specific month and year?**
Yes! Use the `get_folha_pagamento` tool by providing the `exercicio` (year) and `mes` (month). The agent will return a summary of personnel spending for that period.

**How do I check government contracts for a specific year?**
You can use the `get_contratos` tool with the `exercicio` parameter. This will list the contracts registered in the state's system for the requested year.

**Is it possible to track outstanding debts (Restos a Pagar)?**
Yes, the `get_restos_a_pagar` tool allows you to fetch data on expenses that were committed but not yet paid from previous fiscal years.