@titanos/mcp-agents

Model Context Protocol (MCP) server pra orquestrar ferramentas do Titanos em clientes externos como Claude Code, Cursor, Hermes, OpenClaw e qualquer outro cliente MCP.

Ele expõe geração de listing (Super Listing Power + Creative), lookup de produto Amazon, mineração de produtos Amazon multi-país, top vendidos, oportunidades de private label, descoberta de categorias, tools Seller Central (listings, estoque, pedidos, auditoria, write e relatórios SP-API), Olist Tiny ERP REST v3 via Titanos OAuth e Titanos Tools — Cadastros para produtos, fornecedores, marcas, categorias, NCM/tributação e caixas.

⚡ Quick Start

{
  "mcpServers": {
    "titanos-agents": {
      "command": "npx",
      "args": ["-y", "@titanos/mcp-agents@1"],
      "env": {
        "TITANOS_API_KEY": "tnk_live_xxxxxxxxxxxx",
        "TITANOS_API_URL": "https://www.titanos.com.br"
      }
    }
  }
}

Cole no arquivo de config do seu cliente MCP (Claude Desktop, Cursor, etc) e reinicie.

📋 Pré-requisitos

• Conta Titanos com plano Scale ou superior (hierarchy_level >= 30)
• API Key gerada em /conta/configuracoes → aba MCP / API
• Node.js 20+

🛠️ Tools expostas

invoke_listing_power

Dispara o agente Super Listing Power. Gera até 5 pares título (máx. 75 chars) + destaque do produto (máx. 125 chars), bullets, descrição, keywords backend, imagens de listing + A+. Retorna request_id em ~1s; use wait_for_result ou get_result pra resultado final (3-15 min).

Input:

{
  source: "manual" | "amazon_url",
  produto?: { nome: string, descricao: string },  // se source=manual
  amazon_url?: string,                             // se source=amazon_url
  imagens?: string[],                              // URLs HTTPS, máx 4
  gerar_imagens?: boolean,
  gerar_aplus?: boolean,
  gerar_mineracao?: boolean,
  gerar_mercado_livre?: boolean,
  modelo_texto?: TextModelPreset,
  modelo_imagem?: ImageModelPreset,
  aplus_quality?: "low" | "medium" | "high",
  aplus_resolution?: "2K" | "4K",
  aplus_num_imagens?: 1 | 2 | 3 | 4,
  pais?: "brasil" | "estados_unidos" | "espanha" | "reino_unido" | "alemanha" | "franca" | "japao" | "canada" | "italia" | "india" | "mexico" | "australia",
  idempotency_key?: string,                        // recomendado
}

Custo: 4-30 créditos (dinâmico por flags + modelo).

invoke_listing_creative

Análogo ao Power, mas com brief psicográfico + copy estruturada + plano de imagem cinematográfico. Admin only atualmente.

get_result

Polla resultado por request_id. Não-bloqueante. Retorna status processando | concluido | concluido_parcial | erro.

wait_for_result

Bloqueia até resultado pronto (default 300s, max 600s). Polling interno adaptativo (5s → 15s).

lookup_amazon_product

Lookup de dados de produto Amazon (título, preço, ranking, categorias, imagens, histórico). Cache hit grátis, cache miss cobra 1 crédito (mcp_amazon_lookup).

find_categories

Descobre IDs de categorias Amazon por termo e pais. Use antes das tools de mineração quando você souber o nicho, mas não souber o categoria_id.

O retorno já vem sem wrappers internos e inclui breadcrumb, categoria_final e usar_em_busca. Para o agente, a regra é: prefira categoria_final: true e repasse usar_em_busca para a próxima tool.

Input:

{
  "pais": "brasil",
  "termo": "pet",
  "limite": 10,
  "somente_visiveis": true,
  "incluir_arvore": true
}

Custo: gratuito.

search_products

Busca produtos para vender na Amazon usando presets ou filtros granulares. Suporta Brasil, Estados Unidos, Espanha e demais paises aceitos pelo campo pais. Cada produto retornado com incluir_detalhes: true inclui score_oportunidade, classificacao, motivos_recomendacao e alertas_risco para a IA explicar as recomendações.

Input:

{
  "pais": "espanha",
  "palavra_chave": "cafetera italiana acero",
  "categoria_id": 123456,
  "categoria_modo": "final",
  "preset": "hot_picks",
  "preco_min": 20,
  "preco_max": 90,
  "marcas": ["Bialetti"],
  "cadastrado_ultimos_dias": 45,
  "tem_a_plus": false,
  "produto_adulto": false,
  "produtos_genericos": true,
  "tem_avaliacoes": true,
  "avaliacoes_min": 10,
  "avaliacoes_max": 500,
  "rating_min": 3.8,
  "rating_max": 4.8,
  "buy_box_amazon": false,
  "buy_box_fba": true,
  "buy_box_desqualificado": false,
  "disponibilidade_amazon": "sem_oferta",
  "ordenar_por": "vendas_desc",
  "limite": 20,
  "incluir_detalhes": true,
  "idempotency_key": "busca-hot-picks-200-2026-05-11"
}

Presets disponíveis: hot_picks, low_competition, rising_stars, amazon_absent.

Filtros principais: palavra_chave, categoria_id, preco_min/preco_max, bsr_max, marcas, marca_exclui, vendas_mensais_min/max, tem_avaliacoes, avaliacoes_min/max, rating_min/max, buy_box_amazon, buy_box_fba, buy_box_desqualificado, disponibilidade_amazon, tem_a_plus, produto_adulto, produtos_genericos, cadastrado_ultimos_dias, peso_max_kg e ordenar_por.

Use produtos_genericos: true quando quiser procurar produtos sem marca forte. O Titanos aplica internamente as variações de marca generic, generico, genérico, genérica, genericos, genérico2 e genéric.

Custo: 1 crédito sem detalhes, 3 créditos com incluir_detalhes: true.

get_best_sellers

Retorna os produtos mais vendidos de uma categoria Amazon no marketplace escolhido. Use para perguntas de ranking, líderes de categoria e validação de demanda.

Input:

{
  "pais": "brasil",
  "categoria_id": 7841837011,
  "periodo": "atual",
  "limite": 30
}

Custo: 1 crédito sem detalhes, 3 créditos com incluir_detalhes: true.

find_private_label_opportunities

Encontra oportunidades de private label com demanda mínima, concorrência menor, limite de reviews e filtro de peso. Use para sugerir produtos de marca própria ou importação.

Input:

{
  "pais": "brasil",
  "categoria_id": 6740748011,
  "categoria_modo": "final",
  "produtos_genericos": true,
  "preco_min": 30,
  "preco_max": 200,
  "vendas_mensais_min": 100,
  "peso_max_kg": 1,
  "limite": 30
}

Custo: 3 créditos por busca.

list_seller_connections

Lista contas Seller Central conectadas via OAuth SP-API no Titanos. Use antes de get_listings para descobrir connection_id e marketplace.

Pré-requisito: conectar em /conta/configuracoes?tab=amazon e incluir scope seller:connections:read na API Key.

Custo: gratuito.

Olist Tiny ERP

Use get_olist_guide no início, depois list_olist_connections, olist_get_catalog e olist_call_endpoint.

Tools:

• get_olist_guide: guia operacional, scopes, custos, rate limits e idempotência. Scope olist:connections:read. Gratuito.
• list_olist_connections: lista contas Olist conectadas via OAuth no Titanos. Scope olist:connections:read. Gratuito.
• olist_get_catalog: lista endpoints REST v3 catalogados, com tool, method, path, resource, scope, write e path_params. Gratuito.
• olist_call_endpoint: executa uma tool catalogada. Não aceita URL livre. Requer o scope exato retornado pelo catálogo. Consome franquia Olist MCP ou 5 créditos após franquia.

Exemplo:

{
  "tool": "olist_pedidos_get",
  "connection_id": "323cde3a-6704-4ccf-8c2a-ba002973bd12",
  "path_params": { "idPedido": 123 },
  "query": { "incluir_itens": true }
}

Para POST/PUT/DELETE, envie idempotency_key estável e peça confirmação humana antes de operações fiscais, financeiras, estoque/preço em massa ou exclusões.

Titanos Tools — Cadastros

Tools CRUD para os cadastros operacionais do Titanos:

• Produtos: list_titanos_produtos, get_titanos_produto, create_titanos_produto, update_titanos_produto, delete_titanos_produto
• Fornecedores: list_titanos_fornecedores, get_titanos_fornecedor, create_titanos_fornecedor, update_titanos_fornecedor, delete_titanos_fornecedor
• Marcas: list_titanos_marcas, get_titanos_marca, create_titanos_marca, update_titanos_marca, delete_titanos_marca
• Categorias: list_titanos_categorias, get_titanos_categoria, create_titanos_categoria, update_titanos_categoria, delete_titanos_categoria
• NCM/tributação: list_titanos_ncm_tributacao, get_titanos_ncm_tributacao, get_titanos_ncm_tributacao_by_codigo, create_titanos_ncm_tributacao, update_titanos_ncm_tributacao, delete_titanos_ncm_tributacao
• Caixas: list_titanos_caixas, get_titanos_caixa, create_titanos_caixa, update_titanos_caixa, delete_titanos_caixa

Scopes: titanos:cadastros:<entidade>:read para list/get e titanos:cadastros:<entidade>:write para create/update/delete.

get_listings

Consulta listings read-only da conta conectada (SKU, ASIN, título, status, fulfillment, issues).

Input:

{
  "connection_id": "323cde3a-6704-4ccf-8c2a-ba002973bd12",
  "marketplace_id": "A2Q3Y263D00KWC",
  "filters": {
    "page_size": 20,
    "status": "BUYABLE"
  }
}

Filtros: sku (item único), asin, status (BUYABLE | DISCOVERABLE), page_size, page_token.

Pré-requisito: scope seller:listings:read na API Key.

Custo: gratuito.

get_listing

Consulta um listing por SKU com payload completo (attributes, issues, offers, fulfillment).

Input: { "sku": "MEU-SKU-01", "connection_id": "...", "marketplace_id": "A2Q3Y263D00KWC" }

Scope: seller:listings:read · Custo: gratuito.

get_catalog_item

Catálogo Amazon por ASIN (título, brand, product types, identifiers, imagens, sales ranks).

Input: { "asin": "B0XXXXXXXXX", "marketplace_id": "A2Q3Y263D00KWC" }

Scope: seller:listings:read · Custo: gratuito.

search_product_types

Busca product types por keywords ou item_name (use antes do schema quando o tipo é desconhecido).

Scope: seller:listings:read · Custo: gratuito.

get_product_type_schema

Schema de atributos do product type (property_groups + JSON Schema). Obtenha product_type via listing, catálogo ou busca.

Input: { "product_type": "LUGGAGE", "locale": "pt_BR" }

Scope: seller:listings:read · Custo: gratuito.

get_browse_node_recommendations

Browse nodes (subcategorias) recomendados de um product type, extraídos do JSON Schema da Amazon. Retorna browse_nodes[] com { id, name }. Use o id no atributo recommended_browse_nodes do create_listing para fixar a subcategoria.

Na SP-API não há seletor de árvore de categorias: o product_type define a categoria de cadastro. Muitos tipos não expõem browse nodes (browse_nodes: []) — nesse caso a classificação fica a cargo do próprio product type.

Input: { "product_type": "LUGGAGE", "locale": "pt_BR" }

Fluxo de categoria (new_product): search_product_types → get_product_type_schema → get_browse_node_recommendations (opcional) → create_listing. Scope: seller:listings:read · Custo: gratuito.

list_financial_event_groups

Lista repasses (disbursements) via Finances v0. Retorna financial_event_groups[] com data, valor e status do repasse.

Input: { "financial_event_group_started_after": "2026-05-01T00:00:00Z" }

Scope: seller:finances:read · Custo: gratuito · Janela máx 180 dias.

list_financial_transactions

Taxas, vendas, refunds e ajustes via Finances 2024-06-19. Default aggregate: true (resumo). Drill-down de repasse: financial_event_group_id. Por pedido: order_id.

Input (resumo): { "posted_after": "2026-05-01T00:00:00Z", "aggregate": true }

Input (repasse): { "financial_event_group_id": "...", "aggregate": false, "transaction_status": "RELEASED" }

Scope: seller:finances:read · Custo: gratuito · Guia: get_seller_central_guide({ topic: "finances_reconciliation" }).

get_inventory

Estoque FBA (Inventory API, paginado) e FBM por SKU (fulfillment do listing).

Input: { "filters": { "channel": "ALL", "skus": ["SKU-1"] } }

Scope: seller:inventory:read · Custo: gratuito.

get_orders

Lista pedidos (default últimas 24h). Filtros: datas, status, AFN/MFN. Sem PII.

Scope: seller:orders:read · Custo: gratuito.

get_order

Detalhe do pedido + itens por order_id. Sem PII (sem email/endereço do comprador).

Scope: seller:orders:read · Custo: gratuito.

audit_listings

Audita qualidade de listings (issues Amazon, atributos obrigatórios, título, bullets, imagens, keywords, baseline Rufus). Retorna score 0–100 e findings por SKU.

Input:

{
  "skus": ["SKU-1"],
  "checks": ["amazon_issues", "title_length", "rufus_readiness"],
  "include_listing_data": false
}

Omita skus/asins para auditar a página atual de listings (filters.page_size).

Por quê: priorizar SKUs com maior impacto antes de editar. Scope: seller:listings:read · Custo: gratuito.

get_listing_restrictions

Consulta elegibilidade e gating (APPROVAL_REQUIRED) via Listings Restrictions API.

Input: { "asin": "B0TEST1234" } ou skus[] / asins[] (máx. 20).

Por quê: evitar tentar listar ASIN bloqueado ou que exige aprovação de marca/categoria. Scope: seller:listings:read · Custo: gratuito.

get_listing_change_history

Histórico operacional de snapshots SP-API — timeline por SKU ou scan de listings atualizados recentemente.

Modo SKU: { "sku": "SKU-1" } · Modo scan: omita sku e use filters.last_updated_after.

Por quê: detectar mudanças automáticas de status/preço/issues. Não substitui o View Change History do Seller Central. Scope: seller:listings:read · Custo: gratuito.

update_listing

Atualiza listing via patchListingsItem (SP-API write). Campos amigáveis (updates) ou JSON Patch raw (patches).

Input:

{
  "sku": "SKU-1",
  "updates": { "item_name": "Novo título", "price": 99.9 },
  "dry_run": true
}

Por quê: publicar correções após audit/schema. Sempre use dry_run: true antes de publicar. Scope: seller:listings:write · Custo: gratuito.

create_listing

Cria um listing via putListingsItem (SP-API write). Dois modos:

• offer_only — cria oferta sobre um ASIN existente no catálogo (rápido). Exige asin + price (e geralmente quantity + condition_type).
• new_product — cria produto novo no catálogo. Exige product_type (descubra com search_product_types / get_product_type_schema) + attributes brutos do schema do tipo, ou ao menos item_name + campos convenientes.

Campos convenientes (item_name, brand, bullet_points, product_description, generic_keyword, price, currency, quantity) são convertidos para atributos da Listings Items API; attributes brutos sobrescrevem os convenientes.

Input (offer_only):

{
  "sku": "SKU-1",
  "mode": "offer_only",
  "asin": "B0ABCDEFGH",
  "condition_type": "new_new",
  "price": 99.9,
  "quantity": 10,
  "dry_run": true
}

Input (new_product):

{
  "sku": "SKU-2",
  "mode": "new_product",
  "product_type": "LUGGAGE",
  "item_name": "Mala de viagem 360°",
  "brand": "Acme",
  "bullet_points": ["Resistente", "Rodas 360°"],
  "price": 299.9,
  "quantity": 5,
  "attributes": { "color": [{ "value": "Azul", "marketplace_id": "A2Q3Y263D00KWC" }] },
  "dry_run": true
}

Por quê: publicar novos produtos/ofertas pela IA. Sempre use dry_run: true antes. Para editar listing existente use update_listing. Scope: seller:listings:write · Custo: gratuito.

request_sp_report

Enfileira relatório assíncrono SP-API (Reports 2021-06-30). Allowlist: listings, FBA, restock, vendas/tráfego — sem PII de pedidos.

Input:

{
  "report_type": "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
  "data_start_time": "2026-05-01T00:00:00Z",
  "data_end_time": "2026-05-27T00:00:00Z"
}

Retorna report_id + retry_after_seconds: 45. Leia resource titanos://seller/reports.

Scope: seller:reports:read · Custo: gratuito.

get_sp_report

Poll do relatório + preview TSV quando ready: true.

Input: { "report_id": "amzn1.spreport.xxx", "preview_rows": 25 }

Repita enquanto ready: false. Scope: seller:reports:read · Custo: gratuito.

get_report_metadata

Lista os datasets analíticos disponíveis para o report analyst (estoque FBA, vendas/tráfego por ASIN e por dia): colunas, tipos, descrições e freshness (last_ingested_at, row_count, marketplace). Chame antes de ask_selling_partner_report_analyst. Os datasets são alimentados por request_sp_report.

Input: { "connection_id": "uuid-opcional" }

Scope: seller:reports:read · Custo: gratuito.

ask_selling_partner_report_analyst

Responde perguntas em linguagem natural sobre os relatórios SP-API já ingeridos no warehouse. O planner gera uma consulta estruturada segura (sem SQL livre), restrita aos datasets do get_report_metadata. Não faz chamada SP-API ao vivo (só warehouse + 1 chamada LLM).

Input: { "question": "top 10 ASINs com menos estoque FBA" }

Retorna answer_summary, preview (25 linhas), total_rows, columns e um query_id para paginação/export.

Scope: seller:reports:read · Custo: gratuito (sem créditos Titanos; custo OpenRouter no backend).

paged_query_result

Pagina o resultado completo de uma consulta usando o query_id. Resultado em cache por 24h.

Input: { "query_id": "uuid", "page": 1, "page_size": 50 }

Scope: seller:reports:read · Custo: gratuito.

fetch_full_query_result

Exporta o resultado completo (query_id) em json ou csv. Limite síncrono de 10k linhas — acima disso, refine a pergunta.

Input: { "query_id": "uuid", "format": "csv" }

Scope: seller:reports:read · Custo: gratuito.

Docs detalhados (repo Titanos): docs/architecture/mcp-seller-catalog.md · mcp-seller-inventory.md · mcp-seller-orders.md · mcp-seller-reports.md · mcp-seller-p4-report-analyst-catalog.md

📚 Resources MCP

O servidor expõe resources de auto-documentação que o agente pode ler antes de chamar tools.

Mineração

• titanos://mining/presets — quando usar cada preset.
• titanos://mining/filters — cheat sheet dos filtros públicos.
• titanos://mining/recipes — fluxos completos para produtos quentes, baixa concorrência, private label e top vendidos.
• titanos://mining/categories/br — orientação para escolher a ramificação final correta.
• titanos://mining/sales — interpretar vendas reais vs estimativa BSR.

Seller Central

• titanos://seller/flows — fluxos operacionais: diagnosticar, auditar, corrigir, estoque, pedidos e relatórios.
• titanos://seller/reports — tipos de relatório permitidos, polling assíncrono e preview TSV.
• titanos://seller/scopes — matriz de scopes e quando recriar API Key.
• titanos://seller/tools — índice das 18 tools seller (o quê / quando usar).

Exemplo de fluxo mineração:

1. Leia titanos://mining/recipes.
2. Use find_categories({ "pais": "brasil", "termo": "cosmetico", "incluir_arvore": true, "somente_visiveis": true }).
3. Escolha uma categoria com categoria_final=true.
4. Use find_private_label_opportunities({ "pais": "brasil", "categoria_id": 123, "categoria_modo": "final", "produtos_genericos": true, "peso_max_kg": 1 }).

Exemplo de fluxo seller:

1. Leia titanos://seller/flows e titanos://seller/scopes.
2. list_seller_connections() — obter connection_id.
3. audit_listings({ skus: ["SKU-1"] }) — score e findings.
4. update_listing({ sku: "SKU-1", updates: { item_name: "..." }, dry_run: true }).
5. update_listing({ ..., dry_run: false }) — publicar (scope write).

📦 Shape do resultado (Listing Power / Creative)

Quando status: "concluido" ou "concluido_parcial", o resultado é enxuto por design — só os campos necessários pra publicar/usar o listing. Internals do pipeline (competidores analisados, mineração de público, mercado livre interno, creative brief etc) ficam no DB e não vazam pelo wire MCP.

{
  schema_version: "1.0",
  titulo: string,                     // 1 só (máx. 75 chars Amazon BR)
  titulos_sugeridos: string[],        // até 5 opções de título
  destaque_produto: string,           // 1º destaque pareado (máx. 125 chars)
  destaques_sugeridos: string[],      // até 5 destaques pareados
  bullet_points: string[],
  descricao: string,
  keywords_backend: string[],         // pra Amazon Seller Central
  marketplace_fields: Record<string, unknown>,  // sanitizado, sem chaves internas do pipeline
  imagens_listing: string[],          // URLs HTTPS
  imagens_aplus: string[],            // URLs HTTPS
  parcial: boolean,                   // true se concluido_parcial
  alertas: string[],                  // avisos do pipeline
  custo_creditos_real: number,
  duracao_segundos: number,
}

Limites Amazon BR: título 75 caracteres; destaque do produto 125 caracteres (complementa título curto na PDP). update_listing valida item_name com o mesmo teto de 75 chars.

🔐 Segurança

• API Keys formato tnk_live_* (32 chars prefix + 32 chars secret)
• Hash SHA-256 do plaintext no DB; plaintext mostrado uma única vez na criação
• Scopes granulares:
  • Agentes: agents:listing_power:invoke, agents:listing_creative:invoke, agents:read
  • Mineração: amazon:lookup, mining:search
  • Seller read: seller:connections:read, seller:listings:read, seller:inventory:read, seller:orders:read, seller:reports:read
  • Seller write: seller:listings:write
  • Olist read: olist:connections:read, olist:catalog:read, olist:orders:read, olist:finance:read, olist:documents:read, olist:crm:read
  • Olist write: olist:catalog:write, olist:orders:write, olist:finance:write, olist:documents:write, olist:crm:write
  • Matriz completa: resource titanos://seller/scopes
• Plan gating runtime: cada request valida Scale+ via requireMcpApiKey
• Idempotência atômica nos invokes assíncronos via INSERT ... ON CONFLICT; tools síncronas também enviam Idempotency-Key para retries
• Auto-suspend de keys em downgrade de plano (reativável em upgrade)
• Rate limit: 5 invokes/min/key + concurrency max 2 jobs/key, 3/user, 5/org
• SSRF guard em download de imagens (HTTPS only, IP allowlist, redirect manual, streaming cap)

🧪 Códigos de erro estáveis

INVALID_API_KEY       — key não encontrada ou prefix errado (401)
API_KEY_REVOKED       — revogada ou suspensa (401)
SCOPE_MISSING         — key não tem o scope necessário (403)
PLAN_ACCESS_REQUIRED  — plano < Scale (403)
ADMIN_REQUIRED        — Creative invoke sem isAdmin (403)
INSUFFICIENT_CREDITS  — saldo zerado (402)
VALIDATION_ERROR      — body fora do schema Zod (400)
IMAGE_FETCH_FAILED    — falha download/MIME/tamanho (400)
IMAGE_BLOCKED_PRIVATE_IP — SSRF guard tripou (400)
AMAZON_URL_INVALID    — URL fora do regex (400)
INVALID_FILTERS       — filtros de mineração ausentes ou incoerentes (400)
INVALID_CATEGORY      — categoria_id inexistente para o marketplace escolhido (400)
RESULT_NOT_READY      — request_id não existe ou ainda processando (404)
CONCURRENCY_LIMIT     — limite key/user/org atingido (429)
RATE_LIMITED          — rate limit atingido (429)
IDEMPOTENCY_CONFLICT  — mesma key + body diferente (409)
OLIST_CONNECTION_NOT_FOUND — conta Olist não conectada ou fora do tenant (404)
OLIST_CONNECTION_EXPIRED — refresh token Olist expirou; reautorizar OAuth (403)
OLIST_RATE_LIMITED    — limite Olist atingido; respeitar Retry-After (429)
AGENT_FAILED          — pipeline crashou (500)
INTERNAL_ERROR        — outros erros (500)

Mensagens humanas mudam; códigos são contrato estável.

📊 Catálogo completo (v1.35.0)

O pacote expõe 105 tools MCP (104 backend + wait_for_result client-side): agentes listing, mineração, Seller Central (~30), Olist Tiny ERP (4), Amazon Ads read/write (SP/SB/SD/DSP), report analyst, experimentos, brands/integrations e suporte.

Writes Ads relevantes (#310):

• update_resources / create_resources / delete_resources — SP, SB, SD via resource_type
• update_dsp_resources / create_dsp_resources / delete_dsp_resources — DSP (incl. associações creative↔ad group)

Validação Hermes: ver runbook Titanos.

📦 Versionamento

Pin no major pra patches/minors automáticos:

"args": ["-y", "@titanos/mcp-agents@1"]

Pra produção que precisa de reprodutibilidade total:

"args": ["-y", "@titanos/[email protected]"]

🐛 Troubleshooting

• 401 sem auth: verifique se TITANOS_API_KEY está exportada no env do cliente MCP
• 401 API_KEY_REVOKED / INVALID_API_KEY: confira o key_prefix= no stderr do processo MCP no boot — deve bater com a key ativa no painel Titanos. Keys revogadas continuam no env até você reiniciar o subprocess MCP
• 403 PLAN_ACCESS_REQUIRED: faça upgrade pra Scale em https://www.titanos.com.br/conta/configuracoes?tab=billing
• npx trava: cliente não interativo precisa do flag -y — confirme args: ["-y", "@titanos/mcp-agents@1"]
• Timeout no wait_for_result: jobs do Power+Imagens+A+ podem levar até 15min. Use timeout máximo de 600s ou faça polling com get_result

🤝 Contribuindo

Issues e PRs: https://github.com/gavasques/titanos-mcp

Runbook de publish npm: https://github.com/gavasques/titanos-mcp/blob/main/docs/npm-publish-runbook.md

📄 License

MIT © Guilherme Vasques / Titanos