Pharus MCP
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., "@Pharus MCP analyze recent transactions for suspicious patterns in RIF data"
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.
Pharus MCP
Python MCP (Model Context Protocol) server for integrated discovery and querying of investigative services in the Pharus ecosystem. It exposes specialized tools for analyzing RIF, SIMBA, Telefônica, Telemática, KYT, and Graph data through a decoupled service architecture.
Features
Service Discovery: Semantic catalog of investigative services with metadata and usage examples
MCP Protocol: Full implementation of the Model Context Protocol over HTTP Streamable
Multiple Data Sources: Integration with RIF, SIMBA, Telefônica, Telemática, KYT, and Graphs
Financial Analysis: Specialized analytical tools for investigating transactions and movements
Graph Algorithms: Semantic catalog with automatic algorithm suggestions based on graph metadata
Automatic Documentation: Swagger UI and OpenAPI with accessible HTTP routes
Flexible Configuration: Support for environment variables and per-service configurations
Prerequisites
Python 3.12+
pip (Python package manager)
PowerShell 5.1+ (for Windows) or bash (for Linux/macOS)
Upstream services: RIF, SIMBA, Telefônica, Telemática, KYT, Graphs (as needed)
Installation
1. Set Up Virtual Environment
Create and activate the virtualenv:
python -m venv .venv
.\.venv\Scripts\Activate.ps1On Linux/macOS:
python3 -m venv .venv
source .venv/bin/activate2. Install Dependencies
python -m pip install --upgrade pip
python -m pip install -e .[dev]3. Configure Environment Variables
Copy the example file (optional):
Copy-Item .env.example .envEdit the .env with the base URLs of the services according to your environment:
HOST=127.0.0.1
PORT=8000
LOG_LEVEL=INFO
GRAFO_API_URL=http://localhost:8001
RIF_API_URL=http://localhost:8082
SIMBA_API_URL=http://localhost:8003
TELEFONICA_API_URL=http://localhost:8004
TELEMATICA_API_URL=http://localhost:8005
KYT_API_URL=http://localhost:8006Configuration
Supported Environment Variables:
Variable | Description | Default |
| IP address for server binding |
|
| HTTP port |
|
| Log level (DEBUG, INFO, WARNING, ERROR) |
|
| Base URL for the Graph service |
|
| Base URL for the RIF service |
|
| Base URL for the SIMBA service |
|
| Base URL for the Telefônica service |
|
| Base URL for the Telemática service |
|
| Base URL for the KYT service |
|
| HTTP path for the MCP protocol |
|
| Path for HTTP documentation |
|
Execution
Start the MCP Server (via HTTP)
Method 1: Via Python module (recommended)
.\.venv\Scripts\python -m pharus_mcp --transport http --host 127.0.0.1 --port 8000Method 2: Via startup script
.\.venv\Scripts\python .\scripts\start_server.pyMethod 3: Via shortcut (after installation with -e .[dev])
pharus-start-serverManage Upstream Services
Start RIF, SIMBA, Telefônica, Telemática, KYT, and Graphs:
.\.venv\Scripts\python .\scripts\start_services.pyWaits for startup with a default timeout of 60s.
Check connectivity without starting processes:
.\.venv\Scripts\python .\scripts\start_services.py --check-onlySet custom timeout and strict mode:
.\.venv\Scripts\python .\scripts\start_services.py --timeout 90 --strictStop all services (Windows):
.\.venv\Scripts\python .\scripts\stop_services.pyList PIDs without terminating (dry-run):
.\.venv\Scripts\python .\scripts\stop_services.py --dry-runAccessing the Server
Available HTTP Routes
The MCP protocol runs on the /mcp endpoint (not browser-friendly). For inspection and validation:
Route | Description |
| Redirects to |
| Server health check |
| Interactive Swagger UI |
| Full OpenAPI specification |
| Investigative services catalog |
| List of registered MCP tools |
| List of MCP prompts |
| List of semantic resources |
| Content of a specific resource |
| MCP endpoint (MCP protocol over HTTP) |
Examples:
# Health check
curl http://127.0.0.1:8000/health
# Catálogo de serviços
curl http://127.0.0.1:8000/docs/services
# Detalhe de um serviço (RIF)
curl 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif'Service Catalog
Available Services
Graph - Relational analysis with case graphs, labels, KYT, and algorithms
KYT - Person enrichment via documents, emails, and phone numbers
RIF - Financial intelligence report analysis with transactions and statistics
SIMBA - Bank account and movement queries
Telefônica - Telephony analysis with CDRs, locations, and portability
Telemática - Messaging app and contact analysis
Each service exposes a set of specialized tools and a semantic catalog of recommended usage.
Development
Project Structure
pharus-mcp/
├── src/pharus_mcp/
│ ├── adapters/ # Adaptadores para serviços upstream (RIF, SIMBA, etc.)
│ ├── catalog/ # Catálogo semântico de serviços e algoritmos
│ ├── config/ # Configuração e settings
│ ├── models/ # Modelos de dados (Pydantic)
│ ├── server/ # Servidor FastAPI e registro MCP
│ ├── app.py # Aplicação FastAPI principal
│ ├── cli.py # Interface de linha de comando
│ ├── commands.py # Comandos e orquestração
│ └── __main__.py # Ponto de entrada
├── tests/ # Suite de testes
├── scripts/ # Scripts auxiliares de inicialização
├── pyproject.toml # Configuração Poetry/pip
└── README.md # Este arquivoRun Tests
.\.venv\Scripts\python -m pytestWith verbosity:
.\.venv\Scripts\python -m pytest -vRun a specific test:
.\.venv\Scripts\python -m pytest tests/test_catalog.py::test_catalog_contains_expected_services -vManual Smoke Test (HTTP)
PowerShell:
$headers = @{ Accept = "application/json" }
Invoke-WebRequest -Uri "http://127.0.0.1:8000/health" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/services" -Headers $headers -Method GET
Invoke-WebRequest -Uri "http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif" -Headers $headers -Method GETbash/curl:
curl -s http://127.0.0.1:8000/health | jq .
curl -s http://127.0.0.1:8000/docs/services | jq .
curl -s 'http://127.0.0.1:8000/docs/resource?uri=pharus://services/rif' | jq .Project Dependencies
Main dependencies listed in pyproject.toml:
fastapi - Asynchronous web framework
httpx - Asynchronous HTTP client
pydantic - Data validation
mcp - Model Context Protocol
sqlalchemy - ORM (when applicable)
pytest - Testing framework
python-dotenv - .env support
Contribution
Contributions are welcome! Please:
Fork the repository
Create a branch for your feature (
git checkout -b feature/new-feature)Commit your changes (
git commit -am 'Add new feature')Push to the branch (
git push origin feature/new-feature)Open a Pull Request
Code Standards
Use Python 3.12+ with type hints
Follow PEP 8 standard (formatted with tools like
blackorautopep8)Document functions and classes with docstrings in Portuguese
Write unit tests for new features
Troubleshooting
Error: "not a git repository"
Initialize the repository with git init.
Error: "Connection refused" when calling upstream service
Check if the URL in .env is correct and if the service is active on the expected port.
Error: "Port already in use"
Change the port in .env or use --port on the command line.
Tests failing
Check if upstream services are running. Use --check-only to diagnose:
.\.venv\Scripts\python .\scripts\start_services.py --check-onlyLicense
This project is under the MIT license. See the LICENSE file for details.
Authors and Maintainers
Developed by the MPMG Technology team
For questions, suggestions, or bug reports, open an issue in the GitHub repository.
Last update: April 2026
Version: 1.0.0
Status: Active
Available Tools
63 toolscatalog_describe_serviceC
Describe um servico investigativo especifico do catalogo do Pharus.
Inputs: service (required). Returns: service, operation, query, summary, +6 more
catalog_list_servicesB
Lista os servicos investigativos conhecidos pelo catalogo do Pharus.
Inputs: no named parameters. Returns: service, operation, query, summary, +6 more
grafo_describe_algorithmC
Descreve um algoritmo especifico do modulo de grafos.
Inputs: familia (required), algoritmo (required). Returns: service, operation, query, summary, +6 more
grafo_describe_algorithm_familyD
Descreve uma familia de algoritmos do modulo de grafos.
Inputs: familia (required). Returns: service, operation, query, summary, +6 more
grafo_get_algorithm_helpC
Retorna ajuda em markdown para um enum de algoritmos do grafo-back, quando disponivel.
Inputs: enum_name (required). Returns: service, operation, query, summary, +6 more
grafo_get_graphB
Busca um grafo especifico por UUID.
Inputs: grafo_id (required). Returns: service, operation, query, summary, +6 more
grafo_list_algorithm_enumsB
Lista os enums e valores relevantes para o catalogo de algoritmos do modulo de grafos.
Inputs: no named parameters. Returns: service, operation, query, summary, +6 more
grafo_list_algorithm_familiesB
Lista as familias de algoritmos conhecidas para o modulo de grafos.
Inputs: no named parameters. Returns: service, operation, query, summary, +6 more
grafo_list_algorithmsA
Lista algoritmos do modulo de grafos, opcionalmente filtrando por familia.
Inputs: familia. Returns: service, operation, query, summary, +6 more
grafo_list_graphsC
Lista grafos do modulo de grafo por caso ou criador.
Inputs: caso_id, criado_por_id, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
grafo_list_kyt_layersC
Lista camadas KYT configuradas no modulo de grafo.
Inputs: eh_ativo, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
grafo_list_kyt_relationshipsC
Lista relacionamentos KYT configurados no modulo de grafo.
Inputs: eh_ativo, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
grafo_list_labelsC
Lista labels do modulo de grafo, incluindo schema_propriedades.
Inputs: label_type, label_code, pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
grafo_suggest_algorithms_for_graphB
Sugere algoritmos para um grafo com base em seus metadados e em um objetivo investigativo opcional.
Inputs: grafo_id (required), objetivo. Returns: service, operation, query, summary, +6 more
kyt_get_by_documentC
Consulta a API KYT por documentos, em modo full ou lite.
Inputs: documentos (required), modo. Returns: service, operation, query, summary, +6 more
kyt_get_by_emailC
Consulta a API KYT por email, em modo full ou lite.
Inputs: emails (required), modo. Returns: service, operation, query, summary, +6 more
kyt_get_by_phoneC
Consulta a API KYT por telefone, em modo full ou lite.
Inputs: telefones (required), modo. Returns: service, operation, query, summary, +6 more
kyt_list_framesB
Lista os quadros e atributos conhecidos pela API KYT.
Inputs: no named parameters. Returns: service, operation, query, summary, +6 more
rif_analytics_get_resumoC
Retorna um resumo consolidado dos indicadores analiticos de uma origem.
Inputs: src_id (required), data_inicio, data_fim. Returns: service, operation, query, summary, +6 more
rif_analytics_list_funcoes_por_envolvidoC
Lista as funcoes exercidas por um CPF/CNPJ dentro dos indexadores da origem.
Inputs: src_id (required), cpf_cnpj (required). Returns: service, operation, query, summary, +6 more
rif_analytics_list_maiores_transacoesC
Lista as maiores transacoes associadas a uma origem (src_id).
Inputs: src_id (required), top. Returns: service, operation, query, summary, +6 more
rif_analytics_list_maiores_transacoes_por_pessoaC
Lista as maiores transacoes vinculadas a um CPF/CNPJ em uma origem.
Inputs: src_id (required), cpf_cnpj (required), top. Returns: service, operation, query, summary, +6 more
rif_analytics_list_pessoas_transacoes_por_tipoC
Lista pessoas relacionadas e valores de transacoes por tipo de operacao.
Inputs: src_id (required), cpf_cnpj (required), tipo_transacao (required), top. Returns: service, operation, query, summary, +6 more
simba_list_accountsC
Lista contas do SIMBA com filtros explicitos.
Inputs: banco_id, numero_conta, cpf_cnpj_titular, nome_titular, +2 more. Returns: service, operation, query, summary, +6 more
simba_list_accounts_by_personC
Lista contas do SIMBA por pessoa.
Inputs: cpf_cnpj (required). Returns: service, operation, query, summary, +6 more
simba_list_movements_by_person_and_fileC
Lista movimentacoes do SIMBA por pessoa e identificador de arquivo.
Inputs: cpf_cnpj (required), identificador (required). Returns: service, operation, query, summary, +6 more
simba_list_movements_by_srcC
Lista movimentacoes do SIMBA por src_id.
Inputs: src_id (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_analytics_calls_by_caseC
Lista ligacoes de um numero por src_id com paginacao e ordenacao opcionais.
Inputs: src_id (required), numero_telefone (required), pagina, itens_por_pagina, +2 more. Returns: service, operation, query, summary, +6 more
telefonica_analytics_calls_by_fileC
Lista ligacoes de um numero por arquivo com paginacao e ordenacao opcionais.
Inputs: src_id (required), identificador (required), numero_telefone (required), pagina, +3 more. Returns: service, operation, query, summary, +6 more
telefonica_analytics_call_stats_by_caseC
Retorna estatisticas consolidadas de ligacoes para um numero por src_id.
Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_call_stats_by_fileC
Retorna estatisticas de ligacoes para um numero em arquivo especifico.
Inputs: src_id (required), identificador (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_connections_by_numberC
Lista conexoes de dados moveis de um numero por src_id.
Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_distinct_numbers_by_caseB
Conta numeros distintos de origem e destino por src_id.
Inputs: src_id (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_distinct_numbers_by_fileC
Conta numeros distintos de origem e destino por arquivo da Telefonica.
Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_locations_by_numberC
Lista linha do tempo de locais por numero (voz + conexoes).
Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more
telefonica_analytics_phones_by_antennaC
Lista telefones conectados a uma antena da Telefonica em um periodo opcional.
Inputs: src_id (required), cgi_erb (required), data_inicio, data_fim. Returns: service, operation, query, summary, +6 more
telefonica_analytics_portability_by_numberC
Lista eventos de portabilidade de um numero por src_id.
Inputs: src_id (required), numero_telefone (required). Returns: service, operation, query, summary, +6 more
telefonica_get_fileC
Busca um arquivo da Telefonica por src_id e identificador.
Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more
telefonica_get_file_statusC
Retorna o status de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required). Returns: service, operation, query, summary, +6 more
telefonica_list_antennasC
Lista dados de antena de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_connectionsC
Lista conexoes de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_filesC
Lista arquivos da Telefonica por src_id.
Inputs: src_id (required). Returns: service, operation, query, summary, +6 more
telefonica_list_messagesC
Lista mensagens de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_nat_ipsC
Lista IPs nateados de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_portability_eventsC
Lista eventos de portabilidade de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_supplementalC
Lista dados suplementares de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telefonica_list_voiceC
Lista registros de voz de um arquivo da Telefonica.
Inputs: src_id (required), identificador (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_analytics_by_accountC
Retorna metricas analiticas da Telematica por source_id e identificador_conta.
Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more
telematica_analytics_by_sourceC
Retorna metricas analiticas da Telematica por source_id.
Inputs: source_id (required). Returns: service, operation, query, summary, +6 more
telematica_analytics_connections_by_deviceC
Retorna total de conexoes da conta agrupado por dispositivo.
Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more
telematica_analytics_contacts_by_cityC
Retorna distribuicao de contatos por municipio para a conta.
Inputs: source_id (required), identificador_conta (required). Returns: service, operation, query, summary, +6 more
telematica_analytics_distinct_ips_by_dayC
Retorna serie temporal de IPs distintos por dia da conta.
Inputs: source_id (required), identificador_conta (required), top_n, data_inicio, +1 more. Returns: service, operation, query, summary, +6 more
telematica_analytics_recent_groupsC
Retorna grupos recentes da conta com filtros opcionais de periodo.
Inputs: source_id (required), identificador_conta (required), top_n, data_inicio, +1 more. Returns: service, operation, query, summary, +6 more
telematica_analytics_relevant_groupsC
Retorna os grupos mais relevantes da conta por quantidade de participantes.
Inputs: source_id (required), identificador_conta (required), top_n. Returns: service, operation, query, summary, +6 more
telematica_analytics_verify_contactsC
Verifica se numeros informados sao contatos da conta e se ha simetria.
Inputs: source_id (required), identificador_conta (required), numeros (required). Returns: service, operation, query, summary, +6 more
telematica_get_recordB
Busca um registro detalhado da Telematica por UUID.
Inputs: registro_id (required). Returns: service, operation, query, summary, +6 more
telematica_list_connectionsC
Lista conexoes de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_contactsC
Lista contatos de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_devicesC
Lista dispositivos de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_emailsC
Lista emails de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_groupsC
Lista grupos de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_ipsC
Lista enderecos IP de registros da Telematica.
Inputs: registro_ids (required), pagina, itens_por_pagina. Returns: service, operation, query, summary, +6 more
telematica_list_recordsB
Lista registros da Telematica por origem/controle ou por usuario.
Inputs: source_id, identificador, criado_por_id, pagina, +1 more. Returns: service, operation, query, summary, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
Tools are well-organized into distinct modules (catalog, grafo, kyt, rif_analytics, simba, telefonica, telematica), with clear separation of purposes within each module. Some minor overlap exists within modules (e.g., multiple list tools for telefonica files), but descriptions clarify specific contexts like 'by_case' vs 'by_file'.
Tool names follow a highly consistent snake_case pattern with a clear module_action_resource structure (e.g., grafo_list_algorithms, telefonica_analytics_calls_by_case). This predictability makes it easy for agents to understand and navigate the toolset across all 63 tools.
With 63 tools, the count is excessive for a single server, making it overwhelming for agents to manage. While the tools cover multiple investigative domains, such a large number suggests poor scoping and could lead to confusion or inefficiency in tool selection.
The toolset provides comprehensive coverage for investigative analysis across multiple data sources (e.g., graphs, telecom, financial), with CRUD-like operations for listing, describing, and analyzing. Minor gaps may exist in update/delete operations, but the surface supports core investigative workflows effectively.
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).