ITM Platform
Conecte assistentes de IA ao gerenciamento de projetos e portfólios da ITM Platform: pesquise projetos e serviços, revise orçamentos, riscos, problemas e carga de trabalho da equipe, e crie ou atualize tarefas, progresso e lançamentos de horas usando suas próprias permissões da ITM Platform.
Servidor MCP hospedado
npx add-mcp 'https://api.itmplatform.com/v2/_/mcp/'Instala no Claude Code, Codex, Cursor e outros
Documentação
Servidor MCP do ITM Platform
Conecte o ITM Platform a assistentes de IA por meio do Model Context Protocol. O servidor MCP do ITM Platform permite que clientes compatíveis com MCP pesquisem projetos, inspecionem orçamentos, resumam a saúde do portfólio, criem tarefas, registrem riscos e problemas e atualizem detalhes de projetos usando suas permissões do ITM Platform.
Funciona com Claude, VS Code, Cursor, OpenAI Codex, Windsurf, JetBrains AI Assistant e qualquer outro cliente que suporte MCP.
- Documentação pública: developers.itmplatform.com/mcp
- Pacote npm: @itm-platform/mcp-server
- URL MCP hospedada:
https://api.itmplatform.com/v2/_/mcp/
Início Rápido
Conexão hospedada com OAuth
Use o servidor hospedado se o seu cliente de IA suportar servidores MCP remotos. Não há nada para instalar: adicione a URL, faça login com sua conta do ITM Platform e aprove o acesso solicitado.
claude mcp add --scope user --transport http itm-platform https://api.itmplatform.com/v2/_/mcp/
Para outros clientes MCP, use esta URL remota:
https://api.itmplatform.com/v2/_/mcp/
O OAuth é a configuração recomendada para a maioria dos usuários porque seu cliente de IA nunca vê sua senha ou chave de API do ITM Platform.
Após adicionar o servidor, abra seu cliente de IA, digite /mcp onde comandos de barra são suportados, selecione itm-platform e conclua o login OAuth do ITM Platform quando solicitado.
Conexão local com chave de API
Use o pacote npm se preferir executar o servidor localmente, trabalhar atrás de um firewall ou precisar se conectar a uma instância do ITM Platform auto-hospedada.
npx @itm-platform/mcp-server
Seu cliente MCP deve passar estas variáveis de ambiente para o servidor:
| Variável | Valor |
|---|---|
ITM_API_URL | https://api.itmplatform.com |
ITM_COMPANY | Slug da sua empresa/conta |
ITM_API_KEY | Sua chave de API pessoal do ITM Platform |
Exemplo de configuração stdio:
{
"mcpServers": {
"itm-platform": {
"command": "npx",
"args": ["@itm-platform/mcp-server"],
"env": {
"ITM_API_URL": "https://api.itmplatform.com",
"ITM_COMPANY": "{your-account}",
"ITM_API_KEY": "your-api-key"
}
}
}
}
Para criar uma chave de API, faça login no ITM Platform, abra Meu Perfil e gere uma chave na seção Chave de API.
Após configurar o servidor local, reinicie seu cliente de IA e use /mcp ou a lista de servidores MCP do cliente para confirmar que itm-platform está conectado.
O Que um Agente Pode Fazer?
De consultas simples a fluxos de trabalho totalmente automatizados entre sistemas, o MCP desbloqueia casos de uso progressivamente mais poderosos.
Consulta rápida — Faça uma pergunta, obtenha uma resposta:
"Quais riscos estão abertos no meu portfólio?"
Análise em várias etapas — O agente encadeia múltiplas ferramentas e sintetiza resultados:
"Revise todos os projetos que terminam neste trimestre. Sinalize qualquer um com estouro de orçamento, riscos abertos de alto impacto ou conclusão de tarefas abaixo de 60%."
Ações automatizadas em lote — O agente lê, decide e escreve entre projetos:
"Para todo projeto ainda em status Planejamento com data de início no passado, atualize o status para Execução e crie uma tarefa de checklist de kick-off atribuída ao gerente do projeto."
Inteligência agendada — Um agente executa em um cronograma sem prompt humano, puxando tarefas atrasadas toda segunda-feira e publicando um resumo no Slack agrupado por gerente de projeto.
Orquestração entre sistemas — Combine o MCP do ITM Platform com outros servidores MCP (GitHub, Slack, Google Calendar, e-mail). Quando um desenvolvedor faz merge de um PR, um agente encontra a tarefa correspondente no ITM Platform, marca como concluída e, se o projeto atingir 100%, redige um resumo de encerramento e envia por e-mail ao gerente do programa.
O servidor MCP autentica como você, chama as APIs do ITM Platform e retorna apenas os dados que sua conta do ITM Platform tem permissão para acessar.
Capacidades
O servidor expõe 47 ferramentas MCP, 6 recursos e 4 modelos de prompt.
Ferramentas de Leitura
| Ferramenta | O que faz |
|---|---|
search_projects | Encontra projetos por nome, status, tipo ou intervalo de datas |
get_project | Recupera detalhes do projeto com contagens de subcomponentes e orçamento opcional |
search_services | Encontra serviços por nome, status, tipo ou intervalo de datas |
get_service | Recupera detalhes do serviço com contagens de subcomponentes e orçamento opcional |
list_project_tasks | Lista tarefas de um projeto com paginação |
get_task | Recupera detalhes completos de uma única tarefa |
search_tasks | Pesquisa tarefas em todos os projetos por nome, status, responsável, tipo ou intervalo de datas |
get_project_budget | Obtém informações de orçamento, valores reais, receita, custo e margem |
get_project_purchases | Lista ordens de compra de um projeto com paginação |
get_project_revenues | Lista itens de receita de um projeto com paginação |
get_project_risks | Lista riscos do projeto com paginação |
get_project_issues | Lista problemas do projeto com paginação |
get_risk | Recupera detalhes completos de um único risco, incluindo planos de mitigação e contingência |
get_issue | Recupera detalhes completos de um único problema, incluindo campos de resolução e impacto |
list_task_progress | Lista o histórico de progresso (acompanhamento) de uma tarefa |
get_task_effort | Obtém a divisão de esforço de uma tarefa por membro da equipe e por categoria profissional; também serve como lista da equipe da tarefa |
get_project_progress | Obtém relatório de progresso do projeto: curvas esperada, linha de base e real; opcionalmente, todas as entradas de Seguimiento do projeto |
list_service_activities | Lista atividades de um serviço com paginação |
get_service_purchases | Lista ordens de compra de um serviço com paginação |
get_service_revenues | Lista itens de receita de um serviço com paginação |
aggregate_portfolio | Agrupa e resume dados do portfólio |
query_datamart | Executa consultas validadas do DataMart para análise avançada |
search_users | Encontra usuários e membros da equipe; retorna IsNonLoginUser para que usuários sem login (EmailAddress vazio) possam ser identificados por UserId |
get_user | Recupera detalhes do usuário |
get_reference_data | Recupera status, tipos, prioridades e outras listas de referência |
get_custom_fields | Recupera as definições de campos personalizados da conta para projetos, tarefas, riscos, problemas, serviços, atividades, compras ou receitas |
get_custom_field_options | Recupera as opções selecionáveis de um campo personalizado do tipo lista suspensa |
Ferramentas de Escrita
| Ferramenta | O que faz |
|---|---|
create_project | Cria um projeto (Waterfall ou Kanban); o projeto inicia com o status padrão da conta e o usuário criador como gerente do projeto |
create_task | Adiciona uma tarefa, marco (KindId 1) ou tarefa resumo (KindId 2); ParentId constrói a hierarquia Gantt em projetos Waterfall; TaskManagers/TaskMembers atribuem usuários por nome de usuário ou UserId numérico (o id é a única opção para usuários sem login) |
update_task | Atualiza campos da tarefa como status, datas, tipo e pai; TaskManagers/TaskMembers adicionam responsáveis por nome de usuário ou UserId numérico (somente adição, nunca remove) |
create_task_progress | Registra progresso em uma tarefa (percentual, avaliação, notas) com todos os efeitos colaterais |
update_task_progress | Atualiza uma entrada de progresso existente de uma tarefa |
update_task_effort | Define as horas estimadas (planejadas) de uma tarefa por usuário atribuído; dados de esforço aceito e faturamento são preservados |
log_time_entry | Registra horas trabalhadas reais em uma tarefa para um usuário e data; adiciona ou substitui o total do dia, exibindo os totais anteriores e novos |
create_project_progress | Cria uma entrada de progresso (Seguimiento) em nível de projeto: percentual, avaliação e descrição de status; 100% fecha automaticamente o projeto |
update_project_progress | Atualiza uma entrada de progresso existente do projeto |
create_risk | Registra um risco do projeto |
update_risk | Atualiza campos de risco como status, probabilidade, impacto, nível e planos de mitigação ou contingência |
create_issue | Registra um problema do projeto com tipo e status de problema obrigatórios |
update_issue | Atualiza campos do problema como status, tipo e resolução |
update_project | Atualiza campos do projeto como nome, status, datas e prioridade |
create_service | Cria um serviço; ele inicia com o status padrão da conta |
update_service | Atualiza campos do serviço como nome, status, datas e prioridade |
create_activity | Adiciona uma atividade a um serviço (as atividades formam uma lista plana) |
update_activity | Atualiza campos da atividade como status e datas |
bulk_update_task_status | Aplica um status a até 100 tarefas de um projeto em uma única chamada |
bulk_update_activity_status | Aplica um status a até 100 atividades de um serviço em uma única chamada |
As operações de escrita confirmam o estado salvo da API REST do ITM Platform. Resultados de pesquisa baseados no DataMart podem levar até 60 segundos para refletir escritas recentes. Falhas de validação incluem a mensagem acionável retornada pelo REST em vez de apenas o status HTTP.
Roteamento de fontes de dados
As leituras vêm do DataMart sempre que o DataMart possui os dados (sem cota, em todo o portfólio); o REST é reservado para dados que o DataMart não possui, leituras autoritativas de item único (get_task), leituras de confirmação de escrita e dados de referência. As escritas sempre vão para o REST. Quando o DataMart ganha um conjunto de dados, as ferramentas GET correspondentes devem migrar para o DataMart. Regra completa e mapa de roteamento atual: zz_Specifications/progress-history-reads-from-datamart.md.
Quando a conta define campos personalizados, cada sessão é enriquecida com contexto específico da conta: o servidor lista as chaves customFields do DataMart realmente em uso nas instruções de inicialização do MCP e na descrição da ferramenta query_datamart, para que os agentes possam ler e filtrar valores de campos personalizados sem descoberta prévia.
Recursos e Prompts
Os recursos fornecem aos clientes de IA contexto somente leitura, como esquemas do DataMart e calendários de projetos. Os modelos de prompt fornecem fluxos de trabalho guiados para tarefas comuns de análise:
| Prompt | Com o que ajuda |
|---|---|
/project_status | Resume saúde, tarefas, riscos, problemas e orçamento de um projeto |
/portfolio_overview | Analisa status do portfólio, metodologia, orçamento e padrões de entrega |
/team_workload | Revisa atribuições e padrões de carga de trabalho |
/risk_analysis | Avalia exposição a riscos, problemas e impacto no orçamento |
Autenticação e Permissões
O servidor MCP usa o mesmo modelo de identidade e permissão do ITM Platform.
| Método de conexão | Autenticação | Melhor para |
|---|---|---|
| HTTP hospedado | OAuth 2.1 com PKCE | A maioria dos usuários e clientes de IA gerenciados |
| stdio local | Chave de API do ITM Platform | Execução local, redes com firewall, ambientes auto-hospedados |
Sessões OAuth usam escopos:
| Escopo | Permite |
|---|---|
mcp:read | Ferramentas somente leitura, como pesquisa, obtenção, listagem, agregação e consulta |
mcp:write | Ferramentas de leitura mais ferramentas de criação e atualização |
Sessões com chave de API usam as permissões completas do usuário do ITM Platform que gerou a chave.
Acesso por licença:
| Licença | Acesso MCP |
|---|---|
| Administrador da Empresa | Acesso total de leitura e escrita |
| Usuário Completo | Acesso total de leitura e escrita |
| Gerente de Projeto | Acesso de leitura e escrita limitado a projetos gerenciados |
| Membro da Equipe | Bloqueado |
Seu assistente de IA não recebe sua senha ou chave de API do ITM Platform. Os dados do projeto são retornados ao cliente de IA que você escolher, portanto, a política de tratamento de dados do provedor de IA se aplica a qualquer dado que ele processar.
Configuração do Cliente
Use a documentação pública para configuração específica do cliente:
- Claude Code, Claude Desktop, VS Code, Cursor, Codex, Windsurf e JetBrains
- Conectar com OAuth
- Conectar com chave de API
- Solução de problemas
Para qualquer cliente compatível com MCP, os dois valores de conexão são:
| Método | Valor |
|---|---|
| URL remota | https://api.itmplatform.com/v2/_/mcp/ |
| Comando local | npx @itm-platform/mcp-server |
Após adicionar qualquer uma das conexões, abra o comando MCP do cliente ou a lista de servidores. Em clientes que suportam comandos de barra, digite /mcp, selecione itm-platform e autentique quando solicitado.
Auto-Hospedagem
Para um servidor stdio local, configure ITM_API_URL, ITM_COMPANY e ITM_API_KEY ou ITM_TOKEN.
Para um servidor HTTP com OAuth, configure:
| Variável | Descrição |
|---|---|
ITM_API_URL | URL do gateway da API do ITM Platform |
PORT | Porta de escuta HTTP |
ITM_AUTH_URL | URL do servidor de autorização OAuth usado para troca de tokens |
ITM_AUTH_PUBLIC_URL | URL pública OAuth divulgada aos clientes de IA |
MCP_SERVER_URL | URL pública do servidor MCP usada como público-alvo do OAuth |
LOG_LEVEL | Nível de log Pino opcional: debug, info, warn ou error |
ITM_AUDIT_ENABLED | Ativa o registro de auditoria no servidor quando definido como true |
ITM_UI_URL | URL base opcional da interface do ITM Platform (ex.: https://app.itmplatform.com); quando definido, create_project retorna um deep link uiUrl para o projeto criado |
Quando implantado atrás de um proxy reverso, ITM_AUTH_URL pode apontar para um endereço servidor a servidor, enquanto ITM_AUTH_PUBLIC_URL deve ser acessível pelos clientes de IA.
Desenvolvimento
Pré-requisitos:
- Node.js 20 ou posterior
- npm
Instale as dependências, execute os testes e faça o build:
npm install
npm test
npm run build
Execute o servidor de desenvolvimento HTTP:
cp .env.sample .env
npm run dev
O ponto de entrada do pacote é dist/server.js; o executável npm é mcp-server.
Solução de problemas
Se as ferramentas não aparecerem no seu cliente de IA, confirme se a configuração do servidor está no arquivo correto para esse cliente, reinicie o cliente e verifique se npx @itm-platform/mcp-server é executado com sucesso em configurações locais.
Se a autenticação falhar, regenere sua chave de API ou reconecte o servidor OAuth para que seu cliente receba um token novo.
As sessões OAuth tentam automaticamente uma nova tentativa em um 401 downstream, re-trocando o token de portador OAuth por um novo token de sessão. Isso trata casos em que o token de sessão é invalidado externamente (ex.: por um login simultâneo no navegador). Se erros 401 persistirem, o token de portador OAuth provavelmente expirou e o cliente de IA precisa se reautenticar.
Se uma gravação for bem-sucedida, mas uma busca posterior mostrar dados antigos, aguarde até 60 segundos. As gravações são confirmadas imediatamente pela API REST, enquanto os índices de busca do DataMart são atualizados de forma assíncrona.
Mais Ajuda
- Documentação do MCP: modelcontextprotocol.io
- Ajuda do ITM Platform: helpcenter.itmplatform.com
- Documentação para desenvolvedores do ITM Platform: developers.itmplatform.com