MCP do minddy

O minddy MCP permite que um assistente externo leia e altere o trabalho dentro das permissões da sua conta. Conecte o cliente por OAuth, confira os acessos e consulte os esquemas atuais das ferramentas antes de fazer alterações. As conexões MCP do Numo com outros serviços são um recurso separado.

Conectar um assistente externo ao MCP do minddy

Abra a página pública MCP da instância e escolha as instruções do cliente. Use o endpoint exibido, terminado em /api/mcp. Em self-hosted use sua própria origem, não a do Cloud. O cliente precisa aceitar MCP remoto e o fluxo OAuth descrito.

Entre pelo navegador e confira a autorização antes de concedê-la. A conexão age como sua conta minddy, sem acesso a projetos fora das suas permissões. Comece lendo uma tarefa já acessível e confira o projeto retornado.

Selecione seu cliente para exibir o comando ou a configuração de instalação.

Disponibilidade do MCP e acesso à rede

O MCP está incluído no minddy self-hosted e inicia com a aplicação. Funciona imediatamente em /api/mcp, na origem da instância configurada com MINDDY_PUBLIC_APP_URL. A descoberta OAuth e o registro dinâmico de clientes estão incluídos: não é necessário um servidor MCP separado, um aplicativo OAuth dedicado nem um proxy do minddy Cloud. Conecte o cliente MCP ao endpoint da sua instância, entre na conta e conceda acesso pelo consentimento no navegador.

A disponibilidade do serviço não garante que ele seja acessível pela rede. Tanto o cliente MCP quanto o navegador usado para autorização precisam alcançar as URLs MCP e OAuth anunciadas. Se você definir explicitamente OAUTH_ISSUER, essa origem também precisa ser acessível. O cliente deve aceitar a conexão, o fluxo OAuth e o caminho de rede escolhido; alguns clientes exigem HTTPS mesmo em redes privadas.

• Mesmo computador: http://localhost:6463/api/mcp funciona para um cliente compatível executado no computador que hospeda a instância local. localhost e 127.0.0.1 identificam o computador que inicia a conexão. O inicializador de instâncias locais do aplicativo desktop escuta apenas na interface de loopback; outro computador ou um agente hospedado na nuvem não pode acessá-lo diretamente. Abrir a URL localhost do servidor em outro computador aponta para esse outro computador.

• LAN ou VPN: uma instância configurada como http://192.168.1.50 anuncia http://192.168.1.50/api/mcp. Um cliente na LAN, ou conectado por VPN, pode usá-la se o endereço de escuta, a origem configurada, a porta da aplicação, o firewall e o roteamento permitirem o acesso. O navegador precisa alcançar as mesmas URLs de autorização anunciadas. Isso exige uma instalação de servidor acessível; mudar apenas a URL do cliente não expõe um processo limitado ao loopback.

• Fora da rede privada: use uma origem HTTPS acessível, por exemplo https://tickets.example.com/api/mcp, ou outro caminho de rede aceito pelo cliente. Um agente hospedado precisa de seu próprio caminho até a instância; a VPN no computador do navegador, sozinha, não fornece esse caminho. Hospedar o minddy localmente não o expõe automaticamente à Internet.

Escopo e revogação

Clientes externos usam ferramentas disponíveis para tarefas, planos, comentários, páginas, feedback, ciclos, rotinas e caderno dentro dos acessos autorizados. As ferramentas seguem, a cada chamada, o seu papel atual em cada projeto, então uma mudança de papel vale sem reconectar. Como leitor, você recebe as ferramentas de leitura, mais as ferramentas de comentário quando o proprietário ativou Pode comentar para você. MCP está disponível em todos os planos Cloud; a IA do cliente ainda depende da configuração e custos dele.

minddy MCP nas configurações da conta lista acessos externos e controles de revogação. Revogue clientes sem uso ou confiança. O cartão MCP para o Numo da aba IA e Numo é diferente: conecta o Numo a outros serviços. Não cole tokens em tarefas, feedback público nem capturas.

Este exemplo se conecta ao minddy Cloud. Para uma instância autogerenciada, use a origem da sua própria instância; o comando exibido não foi executado para esta captura.

Usar o minddy MCP e descobrir as ferramentas atuais

/api/mcp usa Streamable HTTP, ferramentas sem estado e OAuth 2.1. Conecte sua conta pelo consentimento no navegador; as antigas chaves mdyk_ não são aceitas. Use minddy_list_projects para descobrir UUIDs e leia os esquemas do servidor conectado. /llms-full.txt gera os parâmetros exatos a partir dos registros das ferramentas. Não os reconstrua com uma lista antiga. Cada ferramenta de projeto verifica novamente o acesso e retorna códigos de erro estáveis.

Ler antes de alterar os planos

Para encontrar uma issue, chame minddy_list_issues com query: a busca considera palavras do título e da descrição, um identificador ou um número. Correspondências de texto e identificadores exatos vêm primeiro; uma busca descritiva pode depois acrescentar issues do mesmo projeto encontradas pelo sentido, marcadas com match: "semantic". Leia uma issue assim antes de agir sobre ela. A busca pelo sentido é cobrada da sua conta como Busca de problemas e não acontece se você desligou Indexar tickets.

minddy_get_issue aceita o UUID de uma issue, um identificador de issue como DEMO-42 ou o número da issue; project_id é informado separadamente. plan_tasks informa task_index a partir de zero. minddy_update_plan_task recebe um array tasks com os estados pending, in_progress, completed ou cancelled; um índice inválido faz o lote inteiro ser rejeitado. minddy_append_to_plan acrescenta conteúdo, enquanto minddy_edit_issue_text substitui old_string por new_string em uma correspondência exata e única. Releia um plano que pode ter mudado: substituí-lo por inteiro pode sobrescrever o progresso de outras pessoas. A seção ## Questions fica fora da contagem de tarefas.

As leituras que retornam texto com imagens (minddy_get_issue, minddy_get_objective, minddy_get_page, minddy_get_feedback, minddy_get_scratchpad) as listam em images, cada uma com seu src e texto alternativo. Passe esse src exatamente como está para minddy_get_image: a ferramenta verifica seu acesso ao projeto da imagem, ou se uma imagem do caderno é sua, e retorna a imagem até 10 MB com um download_url assinado válido por cerca de dez minutos. Uma imagem hospedada fora do minddy volta apenas como URL.

Respeitar revisões e propriedade

minddy_list_pages mostra a hierarquia, minddy_search_pages retorna trechos e minddy_get_page retorna Markdown, comentários e valores completos. Prefira edições parciais e use a versão atual ao substituir conteúdo. Preserve as URLs de arquivos e imagens. minddy_create_page com database=true cria um banco de páginas. minddy_update_page_database exige a revisão do banco para alterações no esquema e o valor anterior para alterações nas células.

Para converter um tipo, use operation=convert com propertyId, targetType, revision e preview=true. Confira incompatibleCount, depois envie as mesmas configurações com preview=false e o token retornado. Defina confirmLoss=true somente depois de o usuário autorizar explicitamente a remoção dos valores incompatíveis.

As ferramentas de rotinas, exclusivas do proprietário, criam, alteram, pausam ou removem rotinas acionadas por um agendamento, um evento ou uma nova entrada de banco de dados. Leia antes de criar para evitar duplicatas. minddy_add_resource limita os arquivos a 10 MB; as ferramentas de página não inventam URLs.

Conferir com um exemplo

O exemplo altera a primeira tarefa de um plano já lido. Substitua o UUID do projeto e a issue pelos valores encontrados na descoberta e use o índice da última leitura. Depois confira plan_tasks e plan_progress. Para um erro de acesso, verifique conta e projeto; para conflito, releia e aplique apenas a alteração necessária. Não repita uma alteração externa de resultado incerto sem conferir o resultado.

{
  "project_id": "00000000-0000-4000-8000-000000000001",
  "issue": "DEMO-42",
  "tasks": [{"task_index": 0, "state": "in_progress"}]
}

Escolher um objetivo para um feedback

As leituras de feedback incluem objective_id; minddy_list_feedback aceita um filtro opcional por objetivo (null seleciona solicitações sem objetivo). Use minddy_link_feedback_objective com project_id, feedback_post_id e objective_id apenas quando o usuário solicitar explicitamente; null remove o vínculo. O objetivo deve estar ativo e pertencer ao mesmo projeto. O detalhe do objetivo inclui linked_feedback. O proprietário pode fornecer objective_id a minddy_create_integration para uma chave de feedback ou alterar a configuração com minddy_update_integration_objective. Feedbacks existentes mantêm sua escolha. A conversão herda objetivo e categorias; a revisão do Numo nunca atribui objetivos.