Configurações MCP

Desenvolvedor

Cuidado

As ferramentas de Configurações MCP requerem a role SUPERADMIN. Seu API Token deve pertencer a um usuário com esta role.

O que são as Configurações MCP?

As Configurações MCP controlam como o MCP Gateway se comporta — especificamente as instruções (system prompt) enviadas para clientes de IA e as regras para criação de templates de integração.

---

Ferramentas Disponíveis

Ferramenta	Descrição
get_mcp_settings	Visualiza a configuração atual do MCP Server
update_mcp_settings	Atualiza as instruções e regras

---

Instruções

O campo instructions define como os clientes de IA devem se comportar quando conectados ao MCP Gateway. Por exemplo:

• Sempre chamar get_my_profile primeiro, depois get_workspace_info
• Como lidar com erros de integração
• Regras para criação de templates de integração
• Preferências de formatação para itens de trabalho

Você também pode gerenciar as instruções pela UI do Prodgy: Configurações > MCP Server.

Fluxo de inicialização

As duas primeiras ferramentas que qualquer sessão MCP deve chamar, nessa ordem, são:

1. get_my_profile — carrega a identidade do usuário autenticado (full_name, email, role, position, language), a organization (nome, descrição, indústria, porte, estágio, etc.) e ai_preferences (diretiva pessoal em markdown e o flag de confirmação para ações destrutivas). Disponível apenas em sessões autenticadas de usuário.
2. get_workspace_info — carrega o contexto do workspace/produto (visão, público-alvo, personas, value proposition, integrações ativas).

Se o cliente de IA pular essas chamadas, o gateway faz auto-injection das duas no primeiro CallTool recebido. Chamadas service-to-service (ex.: runtime agentic atendendo o playground) podem entrar no fluxo user-scoped repassando o header X-Prodgy-User-Id — quando presente, get_my_profile resolve o usuário real on-behalf. Sem esse header, get_my_profile retorna unauthenticated_context e apenas get_workspace_info é auto-injetado.

get_my_profile — payload de exemplo

{
  "user": {
    "id": "uuid",
    "full_name": "Santhiago Silva",
    "email": "santhiago.silva@programmers.com.br",
    "role": "superadmin",
    "position": "Senior Product Manager",
    "language": "pt-BR"
  },
  "organization": {
    "id": "uuid",
    "name": "Programmers",
    "info": "Software house with 100+ engineers focused on enterprise platforms.",
    "industry": "Software",
    "size": "medium",
    "stage": "established",
    "website": "https://programmers.com.br",
    "logo_url": "https://..."
  },
  "ai_preferences": {
    "instructions": "Sempre responda em pt-BR. Sempre mostre um TL;DR no final.",
    "instructions_format": "markdown",
    "confirm_destructive_actions": true
  },
  "_instructions": "You now have the user identity, organization metadata and personal AI preferences. Next, call get_workspace_info..."
}

Os workspaces/produtos do usuário não são mais expostos aqui — get_workspace_info é a fonte de verdade para o workspace atual.

Casos extremos tratados pelo gateway:

Cenário	Resposta
language não suportado (fora de pt-BR, en-US, es-ES)	language: ""
Usuário sem organização vinculada	organization: null
Profile sem email/full_name	{ error: "incomplete_profile", missing_fields: [...] }
Service-to-service ou sem userId	{ error: "unauthenticated_context" }

update_my_ai_preferences

Permite que o cliente de IA persista as preferências do usuário sob demanda. Aceita instructions (markdown) e/ou confirm_destructive_actions (boolean) — pelo menos um campo deve ser fornecido.

// Input
{ "instructions": "Sempre responda em pt-BR.", "confirm_destructive_actions": true }

// Output
{
  "user_id": "uuid",
  "ai_preferences": {
    "instructions": "Sempre responda em pt-BR.",
    "instructions_format": "markdown",
    "confirm_destructive_actions": true
  },
  "_message": "Your AI preferences were updated. They will apply on the next get_my_profile call."
}

Quando o LLM deve invocar:

• Persistir uma regra que o usuário pediu explicitamente (“sempre faça X”, “nunca faça Y”, “pare de me perguntar antes de Z”, “salve isso como minha preferência”).
• Sugerir uma regra após perceber a mesma rotina/filtro/formato repetido 3+ vezes na sessão — sempre pedir confirmação antes de gravar.

Quando NÃO invocar:

• De forma proativa, sem solicitação explícita.
• Para registrar fatos descritivos sobre o usuário (time, projetos, histórico). Esses entrarão em uma futura tool de memories, não em preferences.

Casos extremos:

• String vazia em instructions limpa a diretiva markdown.
• Service-to-service ou sem userId → { error: "unauthenticated_context" }.
• Nenhum campo fornecido → { error: "validation_error" }.

Atualizando instruções

"Atualize as instruções do MCP para sempre incluir o número do sprint ao criar itens de trabalho"

---

Regras de Exportação

O campo exports contém regras e exemplos para criação de templates de integração. É o que guia a IA quando create_integration é chamado — garantindo que os templates sigam a estrutura correta com placeholders, padrões de autenticação e definições de ferramentas adequados.

Dica

Configurações MCP bem definidas garantem comportamento consistente entre todos os desenvolvedores da sua organização. Dedique tempo para definir instruções claras que reflitam os fluxos de trabalho e convenções do seu time.