delinea-mcp

DelineaMCP

Servidor MCP para as APIs da Delinea Secret Server e da Plataforma

---

Novidades

• 11 ago 2026 — Protocolo MCP v2 (revisão da especificação 2026-07-28, HTTP streamable) e suporte experimental à API StrongDM estão disponíveis — veja as notas de versão.
• 11 ago 2026 — Somos os provedores originais do caso de uso de vault "sem visibilidade de segredos para o LLM" — cuidado com imitadores ;)

---

Recursos

• Autenticação automática contra o Secret Server
• Conjunto extenso de ferramentas do Secret Server para gerenciar pastas, segredos, usuários, grupos e papéis. Inclui auxiliares de caixa de entrada e solicitações de acesso, além de utilitários para agentes de codificação.
• Ferramentas de compatibilidade com ChatGPT (search e fetch) para interações controladas com IA.
• Ferramentas opcionais de gerenciamento de usuários da Delinea Platform
• Ferramentas opcionais experimentais StrongDM (SDM) — concessões de acesso, auditorias de permissões, ciclo de vida de usuários/papéis, relatórios de saúde e atividade (veja docs/strongdm.md; instale com pip install "delinea-mcp[strongdm]")
• Transports via HTTP streamable (/mcp), Server-Sent Events legados (/mcp/sse) e STDIO
• OAuth 2.0 com registro dinâmico de clientes conforme a especificação MCP
• Suporte a TLS para conexões seguras
• Imagem Docker pronta para execução e ponto de entrada para servidor de desenvolvimento
• Testado com ChatGPT, Claude Desktop, conector remoto Claude, VSCode Copilot e openwebui

Instalação

[!NOTE]

Este projeto usa uv (https://github.com/astral-sh/uv), mas se preferir executar comandos sem isso, você pode rodar pip e venv como de costume, se desejar.

• Instalar Uv
• Inicializar o projeto: uv pip sync requirements.txt
• Usar uv run server.py --config config.json

Configuração

Segredos como senhas continuam vindo de variáveis de ambiente. Forneça DELINEA_PASSWORD no seu ambiente de shell. Recursos opcionais dependem de variáveis adicionais como AZURE_OPENAI_KEY ou PLATFORM_SERVICE_PASSWORD.

Parâmetros não secretos pertencem a config.json:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Para Secret Server Cloud, basta usar a URL da nuvem sem /SecretServer. Especifique ssl_keyfile e ssl_certfile para habilitar HTTPS. Para Let's Encrypt, use os arquivos privkey.pem e fullchain.pem.

O arquivo de configuração suporta as seguintes chaves:

• delinea_username — Nome de usuário do Secret Server. Deve ser um usuário programático com permissão para realizar as tarefas desejadas.
• delinea_base_url — URL base da sua instância do Secret Server.
• platform_hostname — Nome do host do tenant da Plataforma (habilita as ferramentas da Plataforma).
• platform_service_account — Conta de serviço usada com a API da Plataforma.
• platform_tenant_id — ID do tenant para solicitações à API da Plataforma.
• strongdm_api_host — Plano de controle StrongDM (padrão app.strongdm.com:443; variantes para Reino Unido/UE disponíveis). As credenciais vêm das variáveis de ambiente SDM_API_ACCESS_KEY / SDM_API_SECRET_KEY; veja docs/strongdm.md.
• azure_openai_endpoint — Endpoint do Azure OpenAI. Somente se você quiser a geração automática de relatórios (a maioria dos agentes pode gerar seu próprio SQL de relatório, então não habilite a menos que precise).
• azure_openai_deployment — Nome da implantação para o Azure OpenAI.
• auth_mode — Modo de autenticação (none ou oauth). OAuth obviamente não funciona com o transporte stdio.
• transport_mode — stdio para linha de comando ou sse para HTTP. No modo sse, o servidor expõe tanto o endpoint HTTP streamable em /mcp (transporte MCP atual, atende as revisões de protocolo 2024-11-05 até 2026-07-28) quanto os endpoints legados HTTP+SSE em /mcp/sse + /messages/.
• streamable_http_stateless — padrão true; execute /mcp sem sessões do lado do servidor (recomendado para conectores remotos). Defina false para habilitar a operação baseada em sessões com o fluxo GET independente.
• streamable_http_json_response — padrão true; responda com JSON simples em vez de respostas com framing SSE em /mcp.
• chatgpt_disable_scope_checks — Ignora a validação de escopo nas solicitações ChatGPT. Habilite somente se encontrar problemas ao conectar-se ao ChatGPT.
• port — Porta do servidor HTTP no modo sse.
• debug — Habilita registro detalhado.
• external_hostname — Nome do host usado ao construir os públicos-alvo dos tokens OAuth. Não adicione prefixo HTTP(S) ou porta.
• ssl_keyfile — Caminho para a chave SSL para HTTPS. (ex.: privkey.pem)
• ssl_certfile — Caminho para o certificado SSL para HTTPS. (ex.: fullchain.pem)
• registration_psk — Chave pré-compartilhada necessária para registrar clientes OAuth. Você precisará digitar esse segredo no seu navegador para aprovar conexões OAuth.
• jwt_key_path — Localização do par de chaves RSA usado para tokens OAuth. Padrão: .cache/jwt.json. Gerado automaticamente se não existir.
• oauth_db_path — Caminho para o arquivo de banco de dados OAuth. Padrão: .cache/oauth.db. Gerado automaticamente se não existir.
• enabled_tools — Lista de nomes de ferramentas a registrar. Uma lista vazia habilita todas as ferramentas. É altamente recomendável habilitar ferramentas seletivamente por caso de uso ou tarefa. Veja a pasta docs/ para alguns exemplos.
• search_objects — Tipos de objeto permitidos para a ferramenta search. Padrão: ["secret"], mas pode incluir user, folder, group e role.
• fetch_objects — Tipos de objeto permitidos para a ferramenta fetch. Padrão: ["secret"], mas pode incluir os mesmos valores que search_objects.

Executando o Servidor

Inicie o servidor localmente em modo de desenvolvimento:

python server.py

Na inicialização, o servidor solicita um token de acesso e o armazena para solicitações subsequentes à API. Este projeto será expandido para integrar ainda mais com a API do Secret Server.

Ferramentas MCP

O servidor expõe ferramentas MCP para o Secret Server, o diretório de identidade da Delainea Platform e (opcionalmente) o StrongDM. Cada ferramenta publica anotações de comportamento (dicas somente leitura/destrutivas) via tools/list.

Compatibilidade com ChatGPT / deep-research

• search(query) — busca unificada retornando {id, title, url} resultados; os tipos de objeto são limitados pela chave de configuração search_objects (padrão: somente segredos).
• fetch(id) — recupera um único objeto exibido por search; limitado por fetch_objects.

Secret Server

• run_report(sql_query, report_name=None) — cria e executa um relatório temporário.
• ai_generate_and_run_report(description) — gera SQL usando Azure OpenAI e o executa. Requer as variáveis do Azure OpenAI.
• list_example_reports() — lista consultas de exemplo e informações de tabelas.
• get_secret(id, summary=False) — recupera um segredo ou detalhes de resumo.
• get_folder(id) — busca metadados de pasta e filhos.
• search_secrets(query, lookup=False) — busca ou consulta segredos.
• search_folders(query, lookup=False) — busca ou consulta pastas.
• get_secret_environment_variable(secret_id, environment) — gera um script para obter credenciais de segredo no shell especificado.
• check_secret_template(template_id) — recupera detalhes do modelo de segredo.
• check_secret_template_field(template_id, field_id) — verifica se um modelo contém um campo.
• get_secret_template_field(field_id) — recupera detalhes sobre um campo específico do modelo de segredo por ID.
• handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) — aprova ou nega uma solicitação de acesso.
• get_pending_access_requests() — lista solicitações de acesso pendentes.
• get_inbox_messages(read_status_filter=None, take=20, skip=0) — recupera mensagens da caixa de entrada.
• mark_inbox_messages_read(message_ids, read=True) — marca mensagens como lidas ou não lidas.
• create_secret_with_generated_password(name, secret_template_id, password_field_id, items, folder_id=None, site_id=None, comment=None) — cria um segredo cuja senha é gerada no lado do servidor; apenas metadados sanitizados são retornados, o valor nunca chega ao modelo.
• update_secret_generated_password(secret_id, field_slug, password_field_id, comment=None) — rotaciona a senha de um segredo no lado do servidor sem expor o valor.
• update_secret_fields(secret_id, field_updates, comment=None, allow_password_fields=False) — fluxo de ler-modelo → alterar campos não senha → verificar; recusa campos marcados como senha a menos que explicitamente permitido.
• set_secret_field_environment_variable(secret_id, field_slug, environment, source="stdin", comment=None) — emite um script de shell (bash/powershell/cmd) que lê um valor localmente e o envia para o campo do segredo, de modo que o valor ignore completamente o modelo.
• bulk_user_response(user_ids, scenario, comment, confirm=False) — combinador opinativo de incidentes sobre a API de operações em massa de usuários. Cenários: compromise, offboard, unlock, reenable, force_logout; requer confirm=True além de um comentário de auditoria não vazio, e mostra prévias quando não confirmado.
• role_management(action, role_id=None, data=None, params=None) — gerencia papéis. action pode ser list, get, create ou update. Passe parâmetros de consulta opcionais com params ao listar papéis. Exemplo: role_management("update", role_id=3, data={"name": "New Role"}).
• user_role_management(action, user_id, role_ids=None) — atribui ou remove papéis de um usuário. action é get, add ou remove e role_ids é uma lista de identificadores de papel para operações de adicionar/remover.
• group_management(action, group_id=None, data=None, params=None) — lida com grupos. action pode ser get, list, create ou delete. Forneça group_id para get/delete e data ao criar um grupo.
• folder_management(action, folder_id=None, data=None, params=None) — gerencia pastas. action pode ser get, list, create, update ou delete. Forneça folder_id para get, update ou delete e forneça data ao criar ou atualizar uma pasta.
• user_group_management(action, user_id, group_ids=None) — gerencia a associação a grupos de um usuário. action é get, add ou remove. Forneça uma lista de group_ids ao adicionar ou remover associação.
• group_role_management(action, group_id, role_ids=None) — controla papéis em um grupo. Use as ações list, add ou remove. Forneça role_ids ao adicionar ou remover.
• health_check() — consulta o endpoint de verificação de saúde do Secret Server e retorna o status atual do serviço.

Usuários e papéis da Delinea Platform

Desde a v1.0.0, as ferramentas canônicas de usuário direcionam o diretório de identidade da Delainea Platform (requer credenciais platform_hostname + PLATFORM_SERVICE_*; sem elas, as ferramentas retornam orientações em vez de falhar):

• user_management(action, user_id=None, data=None, username=None) — CRUD de usuário na Plataforma. action aceita get, create, update, delete ou search.
• search_users(query) — busca no diretório de usuários da Plataforma.
• platform_role_management(action, role_id=None, data=None, page_size=100, query="%") — CRUD de papéis na Plataforma (list, get, create, update, delete); mutações de papéis são orientadas por descoberta e retornam orientações para tenants cujo escopo da API não as expõe.
• platform_user_role_management(action, role_id, user_principals=None) — list, add ou remove usuários em um papel da Plataforma.
• platform_user_management(...) — alias obsoleto de user_management.

Usuários locais do Secret Server (legado)

Para implantações somente SS sem a Plataforma configurada:

• secretserver_local_user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) — as operações de usuário do Secret Server anteriores à v1.0.0: get, create, update, delete, list_sessions, reset_2fa, reset_password, lock_out. Exemplo: secretserver_local_user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
• search_secretserver_local_users(query) — busca no armazenamento local de usuários do Secret Server.

Ferramentas StrongDM (opcionais, experimentais)

Experimental: o backend do StrongDM ainda não foi verificado contra uma organização SDM real (testado apenas contra a superfície do SDK). Espere arestas a serem polidas e relate problemas. Instalado via o extra strongdm; veja docs/strongdm.md para o guia completo. sdm_search, sdm_audit_access, sdm_grant_access (concessões just-in-time limitadas por tempo ou permanentes), sdm_revoke_access, sdm_user_management (fluxos de onboarding/offboarding), sdm_role_management, sdm_resource_health, sdm_access_requests, sdm_activity_report, sdm_network_status. Ações destrutivas exigem confirmação com comentários de auditoria; correspondências ambíguas de nome retornam candidatos sem mutação.

Use as variáveis de configuração do servidor descritas acima para autenticar. A ferramenta de IA é desabilitada automaticamente se as variáveis do Azure OpenAI estiverem ausentes. Somente os nomes de ferramentas listados em config.json serão registrados. Uma lista vazia habilita todas as ferramentas.

Casos de Uso

A documentação cobre vários fluxos de trabalho para conectar ferramentas ao servidor:- ChatGPT Custom Connector

• Claude Desktop
• Remote Claude Connector
• openwebui for Administration
• VSCode Copilot

Início Rápido com Docker

Um Dockerfile é fornecido para executar o servidor MCP sem instalar dependências Python localmente.

1. Construa a imagem:

docker build -t dev.local/delinea-mcp:latest .

2. Execute o servidor (passe suas credenciais por meio de variáveis de ambiente):

docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Preencha config.json com seus nomes de usuário e URLs conforme mostrado acima.

O contêiner armazena oauth.db e jwt.json em /app/data. Monte um volume (mostrado como mcp-data acima) para que esses arquivos e quaisquer certificados HTTPS persistam entre execuções.

Substitua <https://your-secret-server/SecretServer> pela URL base da sua instância do Secret Server para evitar erros de conexão.

O servidor iniciará na porta 8000 por padrão usando python server.py. Defina a opção port em config.json para substituir o padrão. Ative debug: true para registrar todas as solicitações HTTP recebidas.

Scripts de Exemplo

O script manual_secret_request.py mostra como obter um token OAuth para um ID de segredo específico:

python scripts/manual_secret_request.py <Secret_ID>

Defina as variáveis de ambiente SECRET_USERNAME_<id> e SECRET_PASSWORD_<id> para o segredo antes de executar o script. Opcionalmente, defina DELINEA_BASE_URL para substituir o https://localhost/SecretServer padrão.

Executando Testes

Execute os testes unitários com cobertura (a CI exige um mínimo de 70%):

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Testes ao Vivo

Alguns testes de integração exigem credenciais válidas. Defina as seguintes variáveis de ambiente e o LIVE_SECRET_ID opcional antes de executar a suíte:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Quando essas variáveis estiverem presentes, os testes ao vivo realizarão solicitações reais à API.

Implantação em Produção

As dependências são fixadas em requirements.txt e as versões são marcadas usando Semantic Versioning. Construa a imagem Docker a partir de um commit marcado e implante-a no seu ambiente de produção, passando as variáveis de ambiente necessárias (DELINEA_USERNAME, DELINEA_PASSWORD, opcionalmente DELINEA_BASE_URL). Recursos opcionais dependem de variáveis adicionais:

• PLATFORM_SERVICE_PASSWORD juntamente com PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT e PLATFORM_TENANT_ID habilita as ferramentas de gerenciamento de usuários.
• AZURE_OPENAI_KEY em conjunto com AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT habilita o auxiliar de geração de relatórios de IA.
• SDM_API_ACCESS_KEY e SDM_API_SECRET_KEY habilitam as ferramentas experimentais do StrongDM (requer o extra strongdm; consulte docs/strongdm.md).

Ao executar com transporte OAuth ou SSE, você pode precisar fornecer registration_psk e configurar um external_hostname ou arquivos de certificado HTTPS.

Estrutura do Repositório

• delinea_mcp/ - pacote contendo as ferramentas MCP: tools.py (Secret Server), user_platform_tools.py (Delinea Platform), secretserver_users.py (usuários locais do SS), strongdm_tools.py (StrongDM, opcional), além de transports/ (SSE + HTTP transmissível) e auth/ (o servidor de autorização OAuth embutido).
• server.py - ponto de entrada enxuto que registra tudo com o servidor MCP.
• docs/ - documentação do projeto e o delinea-secret-server-openapi-spec.json gerado.
• scripts/ - exemplos auxiliares incluindo manual_secret_request.py.

Considerações de Segurança

O servidor de autorização OAuth embutido é uma conveniência para desenvolvimento, testes e implantações pequenas; implantações maiores devem colocar o servidor atrás do provedor de identidade da sua organização. Salvaguardas atuais:

• O registro de clientes (/oauth/register) e o formulário de autorização exigem o segredo compartilhado registration_psk (comparado em tempo constante).
• Os valores de redirect_uri são validados contra as URIs registradas para o cliente tanto no formulário de autorização quanto no redirecionamento do código.
• Os tokens de acesso são JWTs RS256 vinculados à audience; a descoberta de recursos segue a RFC 9728 (cabeçalhos /.well-known/oauth-protected-resource e WWW-Authenticate em respostas 401/403).
• Sempre implante com TLS (ssl_keyfile/ssl_certfile ou um proxy de terminação) — tokens de portador e segredos transitam em cada solicitação.
• Escopos de exposição de ferramentas por caso de uso com enabled_tools; os valores de segredos são mantidos fora do contexto do modelo por design (geração de senha no servidor, indireção de script por variável de ambiente, proteções de campos de senha).

Notas de Versão

Consulte CHANGELOG.md para um resumo dos recursos mais recentes e itens do roadmap.

Roadmap

1. Autenticação de passagem
2. Suporte a cliente OAuth Client ID Metadata Documents (CIMD) (o Dynamic Client Registration está obsoleto a partir da revisão 2026-07-28 do protocolo MCP; o fluxo /oauth/register protegido por PSK continua funcionando para os conectores atuais)
3. Expandir a cobertura de ferramentas na Delinea Platform e adicionar outros produtos Delinea

Contribuindo

Contribuições são bem-vindas! Abra issues ou pull requests para quaisquer melhorias. Todo código novo deve incluir testes unitários e passar na suíte de testes existente.

Licença

Este projeto é licenciado sob a MIT License.