Ir para o conteúdo

Conecte seu agente de IA (MCP)

O Tarno traz um servidor MCP neutro para que um agente de IA possa consultar o corpus de marcas do INAPI através do Model Context Protocol (tudo é leitura, exceto cadastrar e remover as solicitações que a própria org vigia, com watch:write). Ele expõe o mesmo contrato de leitura da API REST — apoiado na mesma camada de consultas e nos mesmos schemas — de modo que os dois transportes retornam resultados idênticos.

Endpoint e transporte

Propriedade Valor
Endpoint https://mcp.tarno.cl
Transporte Streamable HTTP (MCP)
Autenticação Header X-API-Key, enviado por requisição
Identidade do servidor tarno-read-mcp

O servidor responde a MCP JSON-RPC sobre o transporte Streamable HTTP. Uma sonda GET /health é a única rota não autenticada; toda chamada de ferramenta é autenticada.

Uma mensagem JSON-RPC por requisição HTTP. Lotes (um array de mensagens no corpo) são rejeitados com HTTP 400 e o erro JSON-RPC -32600. A especificação MCP os removeu na versão 2025-06-18 e os clientes oficiais não os enviam. Cada chamada de ferramenta e cada leitura de um recurso com rota REST gêmea (resources/read) gasta uma unidade de cota e de limite de rajada, igual à sua requisição gêmea em REST. Uma chamada com argumentos que não cumprem o esquema da ferramenta não gasta nada (como um 400 em REST) e devolve o erro no mesmo corpo Problem Details que os demais (status: 400, code: "validation_error" e errors[] por campo); o protocolo (initialize, tools/list, resources/list…) também não gasta.

Autenticação

A autenticação é por ferramenta, não por conexão. Cada handler de ferramenta verifica a chave apresentada antes de ler qualquer coisa, de modo que uma chave ausente ou inválida nunca retorna dados do corpus. Envie sua chave emitida pelo operador no header X-API-Key nas requisições do transporte (placeholder <API_KEY> nesta documentação):

X-API-Key: <API_KEY>

Cada ferramenta exige o mesmo escopo que a sua rota REST gêmea: brands:read a maioria; insights:read as de sistema, agregados e feriados; watch:read/watch:write as quatro de vigilância; legal:read a base documental; e cada relatório, a sua permissão própria. Uma chave irrestrita (escopos vazios) tem as leituras base — veja o guia de autenticação. Uma chave ausente/inválida é rejeitada como um erro de ferramenta unauthorized; uma chave válida sem o escopo é rejeitada como forbidden.

⚠ Os oito relatórios (get_daily_bulletin, get_clearance_report, get_portfolio_report, get_opposition_brief, get_opposition_response_brief, get_conflict_landscape, get_registration_signals e get_filing_context) levam permissão própria: reports:read (todos) ou a do relatório (reports:daily-bulletin:read, reports:clearance:read, reports:portfolio:read, reports:opposition-brief:read, reports:opposition-response-brief:read, reports:conflict-landscape:read, reports:registration-signals:read, reports:filing-context:read). São concedidos explicitamente — uma chave irrestrita (escopos vazios) não os recebe, nem a chave de teste — e cada chamada conta uma unidade de cota.

⚠ analyze_logo também leva permissão própria, logo:analyze, concedida explicitamente com a mesma regra (nem uma chave irrestrita, nem a de teste, nem reports:read a recebem): cada chamada custa dinheiro num terceiro e tem ainda uma cota diária própria (análise de um logotipo). E find_similar_logos, a operação futura, leva a sua, logo:similar, com a mesma regra (nem logo:analyze a abre); não é concedida a nenhuma chave até ser anunciada como disponível.

O handshake initialize no nível de transporte pode ter sucesso sem uma chave — o invariante rígido é que uma chamada de ferramenta nunca retorna dados do corpus a menos que a chave seja válida e tenha o escopo. Sempre envie o header.

Cota

A mesma cota mensal que governa a API REST se aplica ao MCP. Quando uma chave está acima da cota, o servidor responde com HTTP 429 e um header Retry-After (segundos até reiniciar), correspondendo byte a byte à resposta de cota do REST:

HTTP/1.1 429 Too Many Requests
Retry-After: 1209600

{ "type": "https://api.tarno.cl/problems/quota_exceeded", "title": "Rate limit exceeded", "status": 429,
  "detail": "Monthly quota exceeded", "code": "quota_exceeded", "requestId": "..." }

Se a chave não puder ser verificada porque o serviço que valida as chaves está temporariamente indisponível, o servidor responde HTTP 503 com code: "service_unavailable", o mesmo corpo do REST, e a ferramenta não é executada. Repita com espera.

Recursos, prompts e regras

Além das ferramentas, o servidor expõe (o manifesto contract/mcp-manifest-38.json anuncia exatamente estes nomes: um teste constrói o servidor e compara o servido com o anunciado):

  • Recursos — os catálogos do corpus, enumeráveis por URI: iris://catalogs/states, iris://catalogs/sections, iris://catalogs/nice-classes e iris://catalogs/holidays/{year}. Saem da MESMA fonte das rotas REST e são lidos com a MESMA chave e o MESMO escopo da sua rota (brands:read; insights:read para os feriados), e cada leitura gasta uma unidade de cota como a sua rota (os estados, sem rota REST, não gastam); listá-los não pede chave nem gasta. As classes de Nice (list_nice_classes ≡ GET /nice-classes e este recurso) trazem os títulos da edição vigente no Chile HOJE: a 13-2026 até 2026-12-31 e a 13-2027 desde 2027-01-01 (mudam as classes 6, 9, 21, 29 e 31), sem intervenção de ninguém; pt-BR é tradução própria do Tarno. As ferramentas de catálogo (list_nice_classes, list_legal_norms, list_sections, list_holidays) dizem em meta.dataAsOf a data da sua fonte —a OMPI, a BCN, o calendário—, não a da sincronização de marcas; em list_sections, o dia em que a legenda de códigos do INAPI foi lida pela última vez. A família de uma seção (family, e sectionFamily nas anotações) é uma cadeia aberta: hoje presentacion, forma, fondo, publicacion, pago, oposicion, resolucion, renovacion e, desde 2026-10-10, caducidad (os atos de um processo de caducidade por falta de uso; não é o estado caducado) e, desde 2026-10-11, cancelacion_y_limitacion_territorial (os processos de cancelamento e de limitação territorial). Um valor que você não conheça é outra família, não um erro. Cada anotação traz annotationNumber, o número de anotação do INAPI (o «N° de anotación» do processo, o que se cita); uma resolução traz o da anotação que resolve. É null quando não se conhece (o Estado Diario não o imprime): uma lacuna é null, nunca um número suposto. meta.coverageThrough é null nos catálogos (não têm «até»), exceto em list_holidays: o último dia com calendário declarado. Detalhes em Cobertura.
  • Prompts — três, pelo nome real: availability_check (um nome está disponível? — usa search_trademarks com similarTo para as parecidas e q para a coincidência literal), case_history (o que aconteceu com um processo?) e weekly_watch (que semelhantes têm as solicitações que vigio? — o seu único argumento, applicationNumber, é opcional: com ele lê list_similarity_hits dessa solicitação; sem ele, list_watched_applications e list_similarity_hits de todas). Dão sinais, não vereditos.
  • Versão — a data do contrato (2026-10-04), igual ao OpenAPI.
  • Instruções — as quatro regras de leitura do corpus, cada uma com a falha que evita: dizer a data do dado; omitir o que não se sabe; dar sinais, não vereditos; prazos só com seu artigo.

Catálogo de ferramentas

O servidor regista 54 ferramentas —uma delas, find_similar_logos, uma operação futura que hoje responde sempre 503—. Todas leem exceto duas que escrevem, as de vigilância com watch:write (watch_application, unwatch_application), que só mexem no que a própria org vigia. 53 são o gémeo exato de uma rota REST: mesma validação, mesmos dados, mesmos códigos de erro; a que não tem rota é explain_section_code, que lê a base de conhecimento sobre o INAPI e não o corpus. A paridade lê-se «toda ferramenta é uma rota» (salvo essa), não o contrário: quatro rotas REST existem só por serem REST e não têm ferramenta própria — GET /trademarks (ligável/cacheável) é a gémea REST de search_trademarks, GET /trademarks/application-numbers a de list_application_numbers, GET /trademarks/renewal-calendar a de get_renewal_calendar (as três sem o objeto portfolio, que não viaja numa URL), e POST /insights/trademarks/search (para filtros que não cabem numa URL) a de get_trademark_insights. search_trademarks e get_trademark são as de entrada (detalhadas abaixo); o catálogo completo está na tabela a seguir (o seu cliente MCP o enumera com tools/list) e inclui, entre outras, get_trademark_insights (os agregados por groupBy), list_holidays (o calendário de feriados e o intervalo que afirma cobrir), get_system_freshness, list_sync_runs, list_parties e as quatro de vigilância de semelhantes —watch_application, unwatch_application, list_watched_applications, list_similarity_hits— (guia). watch_application devolve o mesmo corpo de REST e não distingue um cadastro novo de um repetido (REST: 201 / 200); unwatch_application devolve { "applicationNumber": "N", "watched": false } (REST: 204 sem corpo). list_watched_applications anuncia o fim de uma vigilância com terminalSince, watchEndsOn (o último dia da vigilância, não um prazo legal) e watchEndBasis; no dia seguinte a solicitação deixa de ser listada. list_similarity_hits devolve só as semelhantes vigentes: uma que passa a estado terminal ou deixa de se parecer desaparece sem aviso e, se voltar, volta com um id novo (como uma vigilância muda). É um feed: next vem sempre, pagina-se enquanto hasMore for true, e o último next, enviado mais tarde como cursor, traz só o que a organização pôde ler depois (como ler o que é novo).

As 54 ferramentas, com a sua rota REST gêmea e o escopo que exigem (reports:read concede também todos os relatórios):

Grupo Ferramenta REST gêmea Escopo O que faz
Marcas search_trademarks POST /trademarks/search brands:read Coleção, lote, semelhança e janela de oposição numa chamada
Marcas get_trademark GET /trademarks/{applicationNumber} brands:read Uma marca, com expansão opcional
Marcas compare_trademarks POST /trademarks/compare brands:read Compara duas marcas via a via: sinais, sem veredito
Marcas get_deadlines GET /trademarks/{applicationNumber}/deadlines brands:read Os prazos de uma marca com a sua norma: recorrer de uma recusa ou de uma aceitação parcial, pagar as taxas de concessão e contestar o traslado de uma oposição
Marcas get_renewal_calendar POST /trademarks/renewal-calendar brands:read Os marcos de renovação (art. 24) de um conjunto de marcas
Marcas list_application_numbers POST /trademarks/application-numbers brands:read Todos os números de pedido que casam com um filtro, em páginas de até 10.000 (next é o cursor; total exato; 409 cursor_stale se uma sincronização correu entre páginas); aceita o objeto portfolio. Sem ele, a mesma resposta que GET /trademarks/application-numbers
Marcas get_trademark_insights GET /insights/trademarks insights:read Agregados por groupBy sobre as marcas que casam
Anotações search_annotations POST /annotations/search brands:read Busca transversal de anotações e feed de atos detectados
Anotações list_trademark_annotations GET /trademarks/{applicationNumber}/annotations brands:read As anotações de uma marca
Anotações get_annotation GET /annotations/{id} brands:read Uma anotação pelo id
Partes list_parties GET /parties brands:read Partes, com a contagem de marcas
Partes get_party GET /parties/{id} brands:read Uma parte
Partes list_party_trademarks GET /parties/{id}/trademarks brands:read As marcas de uma parte, por papel
Partes list_party_relations GET /parties/{id}/relations brands:read As relações de uma parte com outras
Partes get_party_outcomes GET /parties/{id}/outcomes brands:read Os desfechos das marcas de uma parte
Catálogos e cálculo list_nice_classes GET /nice-classes brands:read As 45 classes de Nice da edição vigente
Catálogos e cálculo get_class_stats GET /nice-classes/{niceClass}/stats brands:read Estatísticas de uma classe de Nice, com a sua cobertura
Catálogos e cálculo recommend_nice_classes POST /nice-classes/recommend brands:read Classes de Nice para uma descrição livre
Catálogos e cálculo list_sections GET /sections brands:read As seções do INAPI
Catálogos e cálculo get_section GET /sections/{code} brands:read Uma seção, com as suas equivalências
Catálogos e cálculo explain_section_code — brands:read O que significa um código de seção (sem rota REST)
Catálogos e cálculo list_legal_norms GET /legal-norms brands:read Catálogo de normas citadas
Catálogos e cálculo get_legal_norm GET /legal-norms/{id} brands:read Uma norma, com os seus artigos
Catálogos e cálculo list_holidays GET /holidays insights:read Calendário de feriados e o intervalo que afirma cobrir
Catálogos e cálculo compute_business_days GET /business-days brands:read O N.º dia útil após uma data, com a sua norma
Catálogos e cálculo calculate_fees POST /fee-schedule/calculate brands:read As taxas de um pedido ou renovação
Relatórios get_daily_bulletin GET /reports/daily-bulletin reports:daily-bulletin:read O boletim do Estado Diario de um dia
Relatórios get_clearance_report GET /reports/clearance reports:clearance:read Sinais de disponibilidade de um nome
Relatórios get_conflict_landscape GET /reports/conflict-landscape reports:conflict-landscape:read Quem representa e é titular das semelhantes vivas
Relatórios get_registration_signals GET /reports/registration-signals reports:registration-signals:read O índice orientativo de um nome, por sinais
Relatórios get_filing_context GET /reports/filing-context reports:filing-context:read Os fatos de uma petição, cada um com a sua fonte
Relatórios get_portfolio_report GET /reports/portfolio reports:portfolio:read A carteira de uma parte
Relatórios get_opposition_brief GET /reports/opposition-brief reports:opposition-brief:read Fatos para se opor a uma marca
Relatórios get_opposition_response_brief GET /reports/opposition-response-brief reports:opposition-response-brief:read Fatos para responder a uma oposição
Base documental list_guidance_documents GET /guidance/documents legal:read Os documentos do INAPI com a versão vigente
Base documental get_guidance_document GET /guidance/documents/{code} legal:read Um documento com o Sumário e as versões
Base documental get_guidance_section GET /guidance/documents/{code}/section legal:read Um trecho literal, com página, versão e citações
Base documental search_guidance POST /guidance/search legal:read Buscar nos documentos vigentes
Base documental list_guidance_changes GET /guidance/changes legal:read Que trechos mudaram e quando
Base documental get_legal_norm_article GET /legal-norms/{id}/articles/{article} legal:read O texto de um artigo numa data
Base documental search_statutes POST /legal-norms/search legal:read Buscar artigos de lei
Base documental get_fee_schedule GET /fee-schedule legal:read A tabela de taxas em UTM e em pesos
Base documental list_economic_indicators GET /economic-indicators legal:read Indicadores do SII (UTM, UF, IPC…)
Logos analyze_logo POST /logos/analyze logo:analyze Descreve um logo e propõe códigos de Viena (modelo)
Logos find_similar_logos POST /logos/similar logo:similar FUTURA: hoje sempre 503
Vigilância watch_application POST /watch/applications watch:write Vigiar uma solicitação pelo número
Vigilância unwatch_application DELETE /watch/applications/{applicationNumber} watch:write Deixar de vigiá-la
Vigilância list_watched_applications GET /watch/applications watch:read O que a sua organização vigia
Vigilância list_similarity_hits GET /watch/hits watch:read As semelhantes do que é vigiado
Sistema get_system_me GET /system/me insights:read A sua chave: escopos, cota e uso de 12 meses
Sistema get_system_freshness GET /system/freshness insights:read Atualidade do corpus por fonte
Sistema get_system_coverage GET /system/coverage insights:read Cobertura de ingestão por data de boletim
Sistema get_vigilance_horizon GET /system/vigilance-horizon insights:read A janela que a retenção conserva
Sistema list_sync_runs GET /system/sync-runs insights:read Histórico de sincronizações
> ⚠ [BREAK] 2026-10-04: as dez ferramentas de watchlists (create_watchlist,
> list_watchlists, get_watchlist, update_watchlist, delete_watchlist, add_watchlist_item,
> remove_watchlist_item, list_watchlist_items, list_watchlist_hits, list_watchlist_deliveries)
> foram retiradas de uma vez, sem convivência. Essas quatro as substituem: vigia-se uma solicitação
> do INAPI pelo seu número, sem listas, filtros nem webhook. O mapa antes → depois está no
> guia de Vigilância.

get_renewal_calendar ≡ POST /trademarks/renewal-calendar — o calendário de renovação (2026-09-25). Com from/to obrigatórios (no máximo 366 dias, os dois extremos incluídos) e o filtro de marcas —o lote de até 100 applicationNumber, renewalStatus, holder, niceClass…—, uma linha por (marca, marco de renovação) no intervalo: renewal_window_open e grace_end (Ley 19.039 art. 24), cada uma idêntica ao marco dos milestones[] da marca, mais seu applicationNumber, por data e número. «As datas de renovação da minha lista este ano» é UMA chamada. Pagina com limit + cursor, total exato. q, a similaridade e a janela de oposição são validation_error. Aceita o objeto portfolio (uma marca adicionada à mão está mesmo sem cumprir portfolio.refine); sem ele, a mesma resposta que GET /trademarks/renewal-calendar. Detalhes: relatórios.

list_parties — as duas ordens são rápidas. Sem sort, as partes vêm por volume de marcas (do maior para o menor), servido por uma contagem guardada no fim de cada sincronização; sort: "name" escolhe a página primeiro. Durante uma sincronização em curso a ordem por volume é calculada na hora (mesma resposta, 1–3 s; até 8 s com kind/role). As partes sem marcas nunca são escondidas (trademarkCount: 0), e meta traz dataAsOf e coverageThrough.

list_party_relations — as relações de uma parte (2026-09-24). Gémea de GET /parties/{id}/relations. Arestas tipadas com outras partes: co_holder, represents/represented_by, assigned_to/assigned_from (cessões A07T) e opposed/opposed_by (oponentes identificados). Cada uma com a outra parte, trademarkCount, firstOn/lastOn, até 5 marcas de evidence (+ evidenceTruncated) e coverageFrom: as oposições só desde 2024-04-19 — «nunca se opôs» lê-se «não desde então». Filtros type (lista) e relation. ⛔ Sinais com evidência, nunca veredictos: sem «mesmo grupo» nem semelhança de nome. Detalhe: busca de pessoas.

Os relatórios de uma chamada (2026-09-24). Permissão própria (reports:read ou a do relatório), negada por omissão. Detalhe: relatórios. - get_daily_bulletin ≡ GET /reports/daily-bulletin: o que o Estado Diario publicou em date, linha a linha com partes, paginado, com total exato e o índice do dia em meta.sections ({code, label, count}). Um dia sem boletim ingerido é out_of_coverage (422) com a cobertura, nunca uma lista vazia. - get_clearance_report ≡ GET /reports/clearance: com text e niceClass, as marcas confundíveis por canal (phonetic, fuzzy, semantic) com inOppositionWindow (pertencimento; o fechamento viaja em milestones como opposition_close), os titulares dominantes das classes e as normas citadas nas anotações das confundíveis. ⛔ Sinais, nunca «registrável» nem «infringe». - get_portfolio_report ≡ GET /reports/portfolio: a carteira de UMA parte pelo seu partyId (nunca pelo nome) — contagens por status e por classe, as marcas com um vencimento (expiry) dentro de horizonDays (padrão 90, máximo 366), as que estão hoje na janela de oposição (pertencimento; o fechamento viaja em milestones como opposition_close), quem se opôs, seus representantes e o resumo das suas relações. Cada marca traz seu renewalStatus (art. 24), e byRenewalStatus as conta por status, com as sem data e as não aplicáveis à parte. Detalhes: relatórios. - get_opposition_brief ≡ GET /reports/opposition-brief: para APRESENTAR uma oposição contra applicationNumber — a sua ficha com milestones, se está hoje na janela (pertencimento; o fechamento viaja em milestones como opposition_close), com ownApplicationNumber a sua posição entre as 100 marcas mais parecidas com a sua nas classes dela (similarity; sem a sua marca a chave não viaja), o histórico de oposições dos seus titulares e as normas citadas nas oposições que as marcas deles receberam. Detalhes: relatórios. - get_opposition_response_brief ≡ GET /reports/opposition-response-brief: para RESPONDER às oposições recebidas por applicationNumber — os seus atos de oposição (seção nos três idiomas, normas, oponentes resolvidos) e, por oponente, as suas oposições e as suas marcas vigentes nas classes da sua, buscadas pelo id e nunca pelo nome. As menções de oponente não resolvidas são contadas, nunca nomeadas. Detalhes: relatórios.

⛔ Os cinco dão sinais, nunca veredictos: nenhum diz se uma marca é registrável nem se uma oposição vai prosperar, e nenhum publica uma data de encerramento de oposição fora de milestones.

A base documental (2026-09-28). Permissão própria, legal:read, negada por padrão: uma chave irrestrita não a tem (é concedida explicitamente). Detalhe: base documental. - get_legal_norm_article ≡ GET /legal-norms/{id}/articles/{article}: o texto LITERAL de um artigo de uma norma do catálogo (id de list_legal_norms) na versão que vigorava em asOf (padrão: hoje no Chile), com as suas letras, incisos e notas da BCN. letter/subsection restringem; transitional: true lê o artigo transitório. Um artigo que não pôde ser dividido com segurança é servido inteiro (split: false, article_not_split), nunca com um corte inventado. Uma norma sem texto carregado ou uma data fora das suas janelas é out_of_coverage (422); uma chave repetida, ambiguous_selector (409). dataAsOf é a data da fonte de leis, não a do corpus de marcas. - list_guidance_documents ≡ GET /guidance/documents: os documentos do INAPI (capítulos das Diretrizes, circulares, página e manual de Madrid, taxas), cada um com a sua versão vigente e o seu extractionStatus; filtros kind e q (título, sem acentos). - get_guidance_document ≡ GET /guidance/documents/{code}: um documento com o seu Sumário (todas as secções da versão, em ordem, SEM corpos) e o histórico das suas versões; version lê uma anterior. Uma versão image_only responde com outline: [] e declara-o; uma ocr (imagens lidas por máquina) tem uma secção por página e o seu texto NÃO é literal. - get_guidance_section ≡ GET /guidance/documents/{code}/section: uma secção LITERAL com a sua página, a sua versão, os seus filhos e as normas que cita, por path (III.D.▪1.§7) ou por paragraph (o § que um advogado cita). A citação estável é code + version.seq + path. Um parágrafo repetido é ambiguous_selector (409) com os path; uma versão sem texto (image_only), out_of_coverage (422). dataAsOf é a data da fonte do INAPI. - search_guidance ≡ POST /guidance/search: pesquisa nas secções VIGENTES do INAPI por texto (espanhol, sem acentos) e por semelhança (busca semântica), fundidos; kind/document limitam. - search_statutes ≡ POST /legal-norms/search: pesquisa ARTIGOS de lei no texto que vigora hoje (a mesma regra que get_legal_norm_article), no de asOf, ou com allVersions: true em TODAS as vigências — o mesmo texto repetido entre vigências sai uma vez com todas em validity. norm limita a uma norma do catálogo (sem texto: out_of_coverage).

Ambas: mode hybrid (omissão), text ou semantic; matchedBy diz que canal encontrou cada resultado; se o canal de semelhança não puder correr, hybrid di-lo em meta.channels.semantic: "unavailable" e semantic é service_unavailable (503) — nunca uma lista vazia. Excertos LITERAIS, sem pontuações. Detalhe: pesquisar. - get_fee_schedule ≡ GET /fee-schedule: a tabela de taxas do cap. 13 das Diretrizes em UTM, LITERAL, com amountClp DERIVADO ao ler (amountUtm × utm.value, exato, sem arredondar) com a UTM de utmMonth (omissão: o mês em curso no Chile); utm.basis diz se é a do mês pedido (requested_month) ou a última publicada (latest_published); sem UTM, null. surchargeDoubt é a nota informativa da sobretaxa por renovação tardia: a regra é a tabela das Directrices 2026, e as notas literais das publicações do INAPI que diferem não bloqueiam nada. Detalhe: taxas. - list_economic_indicators ≡ GET /economic-indicators: UTM, UTA, IPC, UF ou dólar observado por code e intervalo from/to, com meta.coverage; um intervalo inteiro fora é out_of_coverage (422). ⚠ Cada linha do IPC leva a sua baseNote: pontos de bases diferentes não se comparam. - list_guidance_changes ≡ GET /guidance/changes: que secções mudaram entre versões de um documento do INAPI ou de um texto da BCN e quando o detetámos (effectiveDate literal da BCN); no máximo 100 secções por alteração (sectionsTruncated). meta.dataAsOf: a fonte do editor pedido ou a mais antiga das duas. - get_annotation com expand: ["citations"] ≡ GET /annotations/{id}?expand=citations: a citação explicada — para cada norma que a anotação cita, o texto LITERAL do artigo/letra que vigorava na sua data (text.asOf; a mesma regra que get_legal_norm_article) e os sinais das Diretrizes: os documentos que citam esse artigo/letra com citingCount/unnamedCount e até três secções, nunca «a» secção que a interpreta. textStatus diz porque uma citação não traz texto. Exige legal:read além de brands:read (sem ela, forbidden sem consumir quota); só no detalhe — as listas rejeitam expand. Sem expand, a anotação de sempre. Detalhe: citação explicada.

Análise e cálculo. Ferramentas neutras que calculam ou reúnem sinais com a sua fonte, nunca vereditos. Detalhe: análise e cálculo. - compute_business_days ≡ GET /business-days: o N.º dia útil ESTRITAMENTE posterior a from (segunda a sexta sem os feriados do calendário — o mesmo cômputo da janela de oposição), com os fins de semana e feriados pulados, a cobertura declarada do calendário e a base legal do cômputo (Ley 19.039 art. 11, Ley 19.880 art. 25). Exatamente um de businessDays (N é você quem define: term.source: caller, term.legalBasis: null — uma contagem, não um prazo) ou preset; o único preset é opposition (art. 5, 30 dias úteis desde a publicação), com a mesma data que o opposition_close da marca. Uma âncora em dia não útil ou um trecho fora do calendário dão basis: estimated com o seu motivo. Permissão brands:read. - calculate_fees ≡ POST /fee-schedule/calculate: as taxas OFICIAIS do INAPI de application_and_registration ou renewal, por niceClassCount ou applicationNumber, em UTM literal e pesos na leitura. Na graça de renovação aplica-se a linha do mês da tabela das Directrices 2026 (renewal.surchargeRuleSource) e o TOTAL é calculado, com a discrepância das outras publicações como nota (renewal.surchargeDoubt); depois dela, lapsed. Nunca inclui o Diario Oficial nem honorários (excluded). Permissão brands:read. - get_party_outcomes ≡ GET /parties/{id}/outcomes: os desfechos das marcas de uma parte por grupo de status publicado, com n e grantShare sobre as decididas (pendentes fora; null sem decididas) e a definição inteira. Não é uma «taxa de sucesso». Permissão brands:read. - compare_trademarks ≡ POST /trademarks/compare: duas marcas (texto ou applicationNumber) comparadas via por via —trigramas, edição, fonética espanhola, similaridade semântica— com os termos genéricos de cada lado DECLARADOS e distinctiveSignals sobre os núcleos; sem pontuação global nem nível (comparar). Permissão brands:read. - get_class_stats ≡ GET /nice-classes/{niceClass}/stats: as estatísticas de uma classe por anos inteiros de depósito (por padrão, os cinco últimos completos): população, desfechos com os grupos de get_party_outcomes, percentis APROXIMADOS (±15 dias) do tempo até o registro com o seu n, proporção com atos de fundo, forma e oposição, e a cobertura dita em coverage. 503 class_stats_pending antes do primeiro cálculo (estatísticas). Permissão brands:read. - get_conflict_landscape ≡ GET /reports/conflict-landscape: as parecidas VIVAS da disponibilidade agregadas por representante e por titular, com evidência e o seu total na classe (panorama). Um RELATÓRIO: permissão reports:conflict-landscape:read ou reports:read. - get_registration_signals ≡ GET /reports/registration-signals: o índice orientativo como DESDOBRAMENTO de seis sinais por classe (1 a 3), cada um com o seu valor, n, evidência e fonte, e um signalIndex 0–100 com a sua fórmula literal e os pesos aplicados (provisórios); «não é um veredito» (índice). Um RELATÓRIO: permissão reports:registration-signals:read ou reports:read. - recommend_nice_classes ≡ POST /nice-classes/recommend: as classes de Nice da edição vigente (13-2026; 13-2027 desde 2027-01-01) para uma descrição livre, por quatro vias declaradas —termos oficiais da OMPI por significado e por texto, títulos e evidência do corpus—, com a atribuição à OMPI (recomendar). Permissão brands:read. - get_filing_context ≡ GET /reports/filing-context: os FATOS de uma peça (procuração, oposição, contestação, resposta a observações, desistência), cada um com sua fonte; os prazos com artigo em milestones (o encerramento da oposição e, desde a mudança de 2026-10-10, a contestação do traslado, opposition_response_close), e os omitidos com seu motivo (milestonesOmitted). Sem redação: quem escreve é o consumidor (dossiê). Um RELATÓRIO: permissão reports:filing-context:read ou reports:read; com expand=legalTexts, também legal:read. - analyze_logo ≡ POST /logos/analyze: um modelo de linguagem (Anthropic) descreve um logotipo nos termos do INAPI e propõe códigos de Viena VCL10, conferidos com o catálogo da OMPI; a resposta diz que foi gerado por um modelo (generatedBy, disclaimer). A imagem vai nos argumentos (base64, ≤ 700 KB, ≤ 2.000 px), é enviada à Anthropic e não é guardada (logotipo). Permissão logo:analyze; cota diária própria (20 por chave, 200 no total); sem chave do provedor no servidor, 503 logo_analysis_not_configured. - find_similar_logos ≡ POST /logos/similar — ⛔ OPERAÇÃO FUTURA, ainda não disponível: as marcas cujo logotipo se parece com uma imagem. Está declarada (entrada: a mesma image de analyze_logo, niceClasses, limit; saída futura: results[] com score e signals.visual de semelhança visual) para que se possa programar contra ela, mas hoje responde sempre 503 image_similarity_not_available, nunca resultados. Não a reprocesse nem apresente a sua resposta como «não há marcas parecidas» (semelhança por imagem). Permissão logo:similar, ainda não concedida a nenhuma chave. É a última de tools/list. - search_annotations aceita também partyId/taxId (+ partyRole, relation) e trademarkStatus; search_trademarks, partyRole junto a taxId (anotações por parte, RUT). - Toda anotação (search_annotations, get_annotation, o boletim) traz inapiTermLabel: o prazo que o INAPI imprime no nome do ato, citado (basis: "inapi_label", p. ex. "30 días") para uma lista fechada de 14 códigos de observações; null nos demais. ⛔ Não é uma data nem um marco (o rótulo do INAPI). - search_annotations por lista e por deteção: applicationNumbers (até 100 marcas por cursor; mais ⇒ 422 batch_too_large), detectedAfter/detectedUntil (quando o corpus o conheceu), denomination e detectedAt em cada anotação e o horizonte meta.detectedThrough para encadear «alterações desde X» sem saltar linhas (por lista e deteção). detectedAfter sozinho (sem marca, lista nem parte) é o feed de todo o corpus: os atos de todas as marcas em ordem de deteção, sem filtros de conteúdo; maxActAgeDays deixa de fora os atos que já tinham mais de N dias ao serem detetados (uma página pode vir curta ou vazia com next: siga-o) (o feed).

get_trademark_insights — as dimensões de groupBy. filedMonth, status, niceClass, holder, representative, desde 2026-09-24 expiresMonth e transferYear, e desde 2026-09-25 renewalStatus. Todas devolvem { key, label, count } com label em es-CL/en/pt-BR, e aplicam o filtro completo de search_trademarks (ou 400). - expiresMonth: marcas por mês de vencimento (key = 2027-03-01, label = «marzo de 2027» / «March 2027» / «março de 2027»). ⚠ As marcas sem data de vencimento não caem em nenhum mês e são DECLARADAS em meta.undatedCount (Σ count + undatedCount = marcas filtradas). São muitas —os pedidos em tramitação ainda não vencem—: não as dê por inexistentes. - transferYear: por ano do ato, as marcas com uma transferência (código INAPI A07T) que retirou um titular conhecido, desde 2011-08-01. Uma marca conta em cada ano em que teve uma; as mudanças de nome não são transferências. - renewalStatus: marcas por seu renewalStatus (o mesmo valor que cada marca traz; art. 24, hoje na hora do Chile): not_due «Renovação ainda não aberta», window_open «Janela de renovação aberta», grace «Em vigor, em período de graça de renovação», lapsed «Prazo de renovação vencido». ⚠ As marcas sem data de vencimento vão para meta.undatedCount e as com data às quais a regra não se aplica (Madri, ou nem registrada nem esperando_renovacion) para meta.notApplicableCount: Σ count + undatedCount + notApplicableCount = marcas filtradas. Nunca um status deduzido. - niceClass rotula o número nos três idiomas: «Clase 9» / «Class 9» / «Classe 9».

Retiradas em 2026-09-24 — a ferramenta de listagem de marcas e a de busca de agregados eram gémeas exatas de search_trademarks e get_trademark_insights (mesmo esquema, mesmo envelope, mesmo caminho). Chamar qualquer uma delas é hoje uma ferramenta desconhecida; a MESMA pergunta, com os mesmos argumentos, faz-se com a que ficou. As rotas REST não mudam.

⚠ O guia de migração de 2026-09-23 é histórico e conserva os nomes de então: onde diz list_trademarks use search_trademarks, e get_trademark_insights em vez de search_trademark_insights (mesmos argumentos).

As pessoas dizem que tipo de parte são. Cada pessoa de get_trademark (parties, holders, representatives, formerParties) traz kind (natural/legal/unknown), kindSource (tax_id/suffix/manual/name_pattern, omitido, nunca null, quando não houve sinal), observation (a cláusula de jurisdição que o INAPI publica colada ao nome, tal qual), publishedName (o nome exatamente como o INAPI o publicou) e revision. Em list_parties cada pessoa traz o mesmo kind, kindSource (aí null quando não houve sinal), publishedName, a cláusula como jurisdictionClause e a revisão como review. São lidos sob o mesmo scope brands:read. A paridade REST≡MCP está verificada com um teste deep-equal contra a base de dados real, incluindo a omissão de kindSource. O que cada um significa: busca de pessoas.

⚠ Nomes anteriores (corte do contrato, [BREAK] de 2026-09-23): estes campos chamavam-se tipo, tipoOrigen, observacion e nombrePublicado, com os valores juridica/desconocido e rut/sufijo; nenhum sai mais.

search_trademarks

A ferramenta de marcas: a coleção com os seus filtros, o lote, a similaridade e a janela de oposição, numa chamada. Idêntica ao REST POST /trademarks/search; sem os três campos que escolhem o motor (similarTo, similarToTrademark, oppositionWindow) responde exatamente o mesmo que GET /trademarks para a mesma pergunta — mesmos filtros, mesmo envelope, mesmo JSON —, lote incluído. (Até 2026-09-24 essa rota GET tinha a sua própria ferramenta gêmea; foi retirada porque era a mesma pergunta.)

Entrada (todos os campos opcionais; ⛔ um argumento que a ferramenta não declara é um erro de entrada, nunca é ignorado):

Campo Tipo Notas
q string Texto livre, até 256 caracteres. Com ele, os resultados são ordenados por relevância.
applicationNumber string[] O lote, até 100, cada número com até 17 caracteres. Os demais filtros se aplicam; veja abaixo.
niceClass integer[] Classes de Nice 1–45 (OR dentro da lista), até 45.
status string[] O status publicado (o derivado), catálogo controlado, até 14.
signType string[] Tipo de signo (catálogo controlado), até 14 códigos de até 20 caracteres.
holder · representative · taxId string[] Partes, OR dentro da lista: um item por nome, com suas vírgulas («PEPSICO, INC.» é um; uma vírgula nunca separa). Até 20 valores de 2 a 256 caracteres com pelo menos uma letra ou dígito; vazio ou [] ⇒ erro de validação; relation (current/former/all, padrão current) diz se vale quem a tem hoje ou quem a teve.
denomination · registrationNumber string A denominação (texto, até 512 caracteres; q, 256) · o número de registro (exato, até 17).
goodsAndServices string ⭐ Texto de produtos e serviços das classes da marca, por palavras, sem acentos nem maiúsculas (calzado encontra «Calzados»); 2–200 caracteres. -palavra exclui, mas é preciso ao menos uma palavra que deva aparecer: só palavras vazias (de la) ou só exclusões (-calzado) é um 400 validation_error.
filedFrom/filedTo · expiresFrom/expiresTo · registeredFrom/registeredTo · publishedFrom/publishedTo YYYY-MM-DD Intervalos das quatro datas.
milestoneFrom/milestoneTo · milestoneKind YYYY-MM-DD · string[] ⭐ Marcas com algum marco no intervalo: expiry, opposition_close, renewal_window_open e/ou grace_end (milestoneKind restringe; sem ele, qualquer um dos quatro). Cada tipo casa exatamente a data que a marca publica (o fechamento, derivado ou estimado; os de renovação, nunca em marcas do regime anterior, de Madri nem fora de registrada/esperando_renovacion). Intervalo invertido = invalid_range; milestoneKind sem intervalo ou com um tipo desconhecido = validation_error.
renewalStatus string[] ⭐ Só as marcas cujo renewalStatus (hoje, hora do Chile) é um de not_due · window_open · grace · lapsed · renewed_expiry_pending (OR). Com o lote, «quais desta lista estão no período de graça?» é UMA chamada, e cada marca devolvida traz esse mesmo renewalStatus. As de null não saem por nenhum; outro valor = validation_error.
liveOnly boolean Exclui as marcas em status terminal: rechazada, denegada, desistida, abandonada, anulada, caducado, vencida.
partyRole string Limita taxId a um papel: holder ou representative. Sem ele, os dois. Exige taxId.
party string[] ⭐ Partes por id (de list_parties) e papel: "<id>:holder" ou "<id>:representative", OR dentro da lista (até 20). O papel significa o mesmo que em list_party_trademarks; vale relation. Serve para partes sem RUT.
includeApplicationNumber · excludeApplicationNumber string[] ⭐ A carteira à mão (até 500 cada): ((filtros de parte ∪ incluídos) − excluídos) ∩ demais filtros. Os filtros de parte são party/holder/representative/taxId; um incluído tem de cumprir os demais filtros; a exclusão ganha; sem filtro de parte, os incluídos são a carteira. Números como o INAPI os escreve (991652209-2).
portfolio object ⭐ A carteira como objeto {party, refine, includeApplicationNumber, excludeApplicationNumber}: (((partes ∩ refine) ∪ incluídos) − excluídos) ∩ filtros de primeiro nível. refine (os filtros de predicado de list_application_numbers) restringe só as marcas das partes: um incluído está sempre; a exclusão ganha; os filtros de primeiro nível aplicam-se a tudo. Até 10.000 números por lista. Com ele, party/includeApplicationNumber/excludeApplicationNumber de primeiro nível são validation_error. Também em list_application_numbers e get_renewal_calendar.
text object ⭐ A busca de texto configurável (vocabulário do Algolia): {query, queryType, typoTolerance, minWordSizefor1Typo, minWordSizefor2Typos, exactOnSingleWordQuery, removeWordsIfNoResults, phonetic, semantic, getRankingInfo}. Com tudo no padrão responde o mesmo que q. Configurado: primeiro o bloco de palavras-chave (determinístico, completo, tamanho exato em total ou, com aproximadas, em meta.keywordTotal; exata → prefixo → palavras → erros → sort), depois as aproximadas de phonetic/semantic (só em meta.estimatedTotal). Com q/denomination é validation_error. Em list_application_numbers e portfolio.refine.text, só como conjunto (phonetic/semantic em false).
similarTo · similarToTrademark · allClasses · oppositionWindow string · string · boolean · string Escolhem o motor em vez de filtrar; veja «Os três campos que escolhem o motor», abaixo. allClasses só vale com similarToTrademark.
citedNorm · article · letter string Declarados, mas não filtram marcas: com qualquer um deles a chamada é um 400 validation_error que nomeia o campo e remete a search_annotations (filtram anotações pela norma que citam).
facets string[] niceClass, status: contagens em meta.facets.
sort string relevance, filedOn:desc… status/status:asc/status:desc ordena pelo status publicado.
limit · cursor · minScore Página (padrão 20, máx. 100) · cursor opaco · piso de relevância.

Saída: o envelope comum do contrato — { results: [...], limit, next, hasMore, total?, meta } —, idêntico ao REST. meta leva sempre dataAsOf e coverageThrough; meta.estimatedTotal é um limite inferior; meta.facets (niceClass, status) só quando pedidas; meta.mode: "advanced" quando um campo concorrente deslocou q. matchedFields[].field nomeia o filtro que fez a marca aparecer (denomination, applicationNumber, registrationNumber, holder, representative, taxId). O payload é o primeiro bloco de texto do resultado (faça o parse como JSON).

O lote. Com applicationNumber a resposta traz as marcas na ordem do pedido e meta.notFound com os números que não existem; os demais filtros SE APLICAM (uma marca que existe e não casa simplesmente não aparece), total é exato e não há página seguinte. limit, cursor, sort, minScore, q, denomination e facets com o lote são um validation_error. Mais de 100 é batch_too_large, nunca um corte silencioso.

Marcos. Cada marca do resultado traz milestones[] ([] se não tiver). Com o lote, «quais marcas desta lista têm um marco nos próximos 30 dias, e quando?» é UMA chamada: { "applicationNumber": [ …até 100… ], "milestoneFrom": "2026-09-24", "milestoneTo": "2026-10-24" }. E «quais marcas fecham a janela de oposição na semana que vem?», outra: { "milestoneKind": ["opposition_close"], "milestoneFrom": "2026-09-28", "milestoneTo": "2026-10-04" }. O core publica as datas; a quem e quando avisar é decisão da sua aplicação.

⛔ Um lote vazio devolve um lote vazio, não a coleção: montar a lista a partir de uma carteira que afinal não tem marcas devolveria, senão, a primeira página do corpus inteiro.

Os três campos que escolhem o motor (mutuamente exclusivos: pedir dois é um validation_error): similarTo (texto livre, ordenado por semelhança em quatro canais: fonético, léxico, semântico e de elemento distintivo; matchedBy diz quais a encontraram), similarToTrademark (uma marca existente: exclui a base e restringe às suas classes; allClasses: true alarga) e oppositionWindow: "open" (marcas com data de publicação cujo 30.º dia útil é hoje ou depois e cujo status não é terminal nem registrada/concedida —o mesmo prazo que o objeto marca publica, que não olha o estado: uma registrada com expired: false NÃO está na janela—; exige niceClass e um de q ou applicationNumber). Com a similaridade, applicationNumber é um validation_error; com a janela é UM número de pedido —a marca de referência contra a qual se ordena—, não um lote: mais de um é um validation_error. Com qualquer dos motores, sort só aceita relevance.

get_trademark

Busca UMA marca pelo número de solicitação, com expansão opcional. Idêntica ao REST GET /trademarks/{applicationNumber}.

Entrada:

Campo Tipo Notas
applicationNumber string O número de solicitação (obrigatório).
expand string[] classes, parties, annotations, encumbrances, norms. O que não se pede viaja null (≠ []). norms (as normas citadas nas anotações, com contagem, datas e ids; sem texto) exige também legal:read.
dedupe boolean Padrão true: as linhas do MESMO fato se colapsam em uma, com as demais em duplicates[]. false devolve cada versão. renewals é idêntico nos dois modos.

Saída: o objeto marca, plano. Um número desconhecido devolve um erro de ferramenta estruturado not_found, refletindo o 404 do REST: status: 404, title: "Not found" e o mesmo detail (trademark 123 not found).

milestones[] viaja SEMPRE: os marcos com data da marca, [] se não houver. Cada um diz de onde vem (basis): source (um dado do INAPI, com o field verbatim) ou derived (um prazo calculado, que leva sempre anchor, rule e legalBasis — sem artigo não há marco derivado). Ou estimated (a mesma forma mais estimateReasons: um prazo que a lei ou o calendário não permitem afirmar). legalBasis é uma lista de {norm, article, role}. Saem expiry (source, de expiresOn) e opposition_close (o fechamento da janela de oposição: Ley 19.039 arts. 5 e 11, Ley 19.880 art. 25; estimated se publicada em dia não útil ou fora da cobertura do calendário; sem publicação não sai), e, nas marcas nacionais registrada ou esperando_renovacion com vencimento a partir de 2022-05-09, renewal_window_open e grace_end (vencimento − 6 e + 6 meses, Ley 19.039 art. 24, Decreto 82/2022 art. 27, Código Civil art. 48 e Ley 19.880 art. 25; grace_end deslocado ao primeiro dia útil quando não é útil). Os quatro se filtram com milestoneKind. ⭐ (44-14) E appeal_close: a data limite para apelar de uma recusa (024) ou de uma aceitação parcial (444), o 15.º dia útil após a sua publicação no Estado Diario (Ley 19.039 art. 17 bis B e 11, Ley 19.880 art. 25), publicado mas não filtrável; a sua âncora auditável e o que se omite e por quê vêm de get_deadlines. ⭐ (2026-10-10) E mais dois, também não filtráveis: opposition_response_close (contestar o traslado de uma oposição: 30.º dia útil após a sua notificação, Ley 19.039 art. 9; estimated se a âncora for deduzida) e grant_fee_close (comprovar o pagamento das taxas de concessão: 60.º dia útil após a notificação da aceitação, Ley 19.039 art. 18 bis E; sempre estimated e com reservation em es/en/pt — a lei conta desde o trânsito em julgado e o INAPI desde a notificação: cite a data com essa ressalva). ⭐ (2026-10-26) E resolution: a data em que o INAPI aceitou ou recusou o pedido (não é um prazo; anchor.kind acceptance/rejection com o ato, Ley 19.039 art. 13 com o papel notification), ausente se o pedido não chegou a ser decidido. ⭐ (2026-10-28) E designation_ceased: a data em que o INAPI declarou cessada uma designação Madrid após um DEATH da OMPI (cessação 1238/1240/1241/1242, não 1237; âncora = o ato de cessação; Protocolo de Madri e seu Regulamento Comum com o papel extinction); aparece quando a marca publica status: caducado por ela; ⭐ (2026-11-04) e também, ancorado no DEATH (anchor.kind: "wipo_death"), quando o cancelamento da OMPI chegou durante o trâmite e o INAPI concedeu depois. ⭐ (2026-10-28) Além dos marcos, umas poucas marcas trazem notices[] em get_trademark: fatos verificados à mão no processo e na OMPI; wipo_designation_ended diz que a OMPI inscreveu que o Chile não está mais designado, com a inscrição como fonte (source.reference, recordedOn, madridMonitorUrl) e o documento do processo como respaldo (corroboration.documentIndex); wipo_refused_recording, que a OMPI não inscreveu a declaração de concessão do INAPI porque o Chile não está designado. Um aviso não decide status nem milestones: decidem-nos as anotações (Avisos). A lista de tipos, com exemplo, está em Marcos.

renewalStatus viaja sempre (em get_trademark e em cada marca de search_trademarks): not_due | window_open | grace | lapsed | renewed_expiry_pending, avaliado na data da resposta (hora do Chile), ou null quando a regra não se aplica — sem data de vencimento, nem registrada nem esperando_renovacion, ou via Madri. Descreve o prazo para pedir a renovação; em grace o registro continua em vigor e ainda pode ser renovado (caduca por falta de renovação só se a graça terminar sem o pedido: Ley 19.039 art. 24, inciso 2º; Decreto 82/2022 art. 27, inciso 2º). renewed_expiry_pending, antes ou depois do vencimento: a renovação já foi concedida e o vencimento publicado ainda não foi atualizado; a marca não publica então renewal_window_open nem grace_end. A regra, em Marcos. Também é um filtro de search_trademarks (renewalStatus), com a mesma regra e a mesma data que o campo.

renewals[] (em get_trademark ≡ GET /trademarks/{applicationNumber}, sempre presente, vazia se não houver nenhum) são os atos de renovação da marca em ordem cronológica, e cada um diz o que é em kind: request (a renovação foi pedida: apresentada, ou observada e pendente; ainda não concedida nessa data), grant (o INAPI a concede, aceita ou inscreve) ou outcome (o INAPI resolve o pedido sem concedê-lo: abandono, desistência, rejeição…). lastRenewalOn é a data do último grant, e é omitido se não houver nenhum: uma renovação pedida e depois abandonada ou rejeitada não conta como renovação.

procedureHistory[] (em get_trademark ≡ GET /trademarks/{applicationNumber}, sempre presente, vazia se não houver nenhum, igual com ou sem dedupe e com qualquer expand) é o índice do processo do INAPI: os passos da tabela de trâmites que a ficha pública do processo mostra e, misturadas com eles por data, as anotações numeradas (petições como uma transferência ou uma renovação, e as resoluções sobre elas). Vem sem as linhas do Estado Diario e sem o agrupamento por fato de annotations[]. Cada entrada traz annotationId (o mesmo id que em annotations[]), date, code (o código do INAPI), inapiText (a legenda do INAPI para esse código, a mesma que sectionName; null se o INAPI nunca o nomeou), reference (o número de resolução ou de petição que o INAPI imprime na linha, como 2026/82718 ou C/2026/123550; null se não imprime nenhum ou se a linha não foi lida desde que é guardada: hoje, a maioria das linhas históricas) e annotationNumber (o número de anotação do INAPI da linha; null num passo da tabela de trâmites).

Uma petição que o INAPI lista como passo e também como anotação numerada aparece uma só vez, como a anotação numerada, emparelhada uma a uma por data e código: duas petições do mesmo código no mesmo dia são duas entradas. Se essa entrada não traz reference, toma a do passo. Um passo que o INAPI devolveu uma vez com a sua observação e outra sem ela aparece uma só vez, com o annotationId da versão com observação. A ordem é por data e, no mesmo dia, pelo lugar de cada código no fluxo do procedimento do INAPI (a aceitação para tramitação 009 antes do pagamento de publicação 439, a concessão 158 antes do título 1230), aprendido dos índices do processo; os códigos sem lugar conhecido vão depois e os demais empates seguem a ordem em que as linhas foram registradas. A posição do INAPI não é guardada, então algum dia ainda pode sair em outra ordem que no INAPI. Uma anotação guardada sem o seu número (falta em parte do histórico) não se distingue de um passo e aparece com annotationNumber: null.

Dois passos do mesmo dia e do mesmo código que o INAPI distingue só pelo número do escrito (reference) são duas entradas. Um passo que o INAPI lista várias vezes igual no mesmo dia (sem texto nem número que o distinga) aparece tantas vezes quantas é listado, e todas as cópias levam o mesmo annotationId, então esse id não é único dentro da lista. Parte do histórico foi guardada antes de isso ser contado e mostra esse passo uma vez até a marca ser lida de novo. As marcas do Protocolo de Madri não têm a entrada «Expediente inicial (*)»: o índice do processo a imprime, mas a ficha pública do INAPI não a publica, e ela não é inventada.

Forma dos erros

Todos os erros de ferramenta compartilham uma única forma: um resultado de ferramenta com isError: true cujo texto é um application/problem+json da RFC 9457 — { "type", "title", "status", "detail", "code", "requestId" } — idêntico ao corpo que a API REST retorna para 4xx/5xx (REST≡MCP). Um cliente pode fazer JSON.parse(text).code de forma uniforme para qualquer erro de ferramenta.

⚠ requestId viaja vazio em MCP: o transporte não tem um id de pedido próprio, e o contrato declara o campo sempre presente. Vazio é «não há», não «esquecemo-nos».

Os code que você pode ver:

code Significado
unauthorized Chave ausente, inválida, revogada ou expirada.
forbidden Chave válida sem o scope requerido (p. ex. brands:read).
validation_error Entrada inválida (p. ex. a regra "exatamente um de businessDays ou preset").
not_found Busca por id de um recurso desconhecido (ou de outro tenant). status 404, com o detail do REST.
query_timeout 504: a consulta excedeu o orçamento de tempo; reprocessável.
service_unavailable 503: dependência temporariamente indisponível (o banco sem recursos, o armazém de vigilâncias, search_trademarks com q quando todos os canais falham —antes um resultado vazio—…); reprocessável.
coverage_not_declared 503 de list_holidays: o calendário não declara nenhum ano coberto; reprocessável.
application_terminal 422 de watch_application: a solicitação existe mas o seu estado é terminal; não pode ser vigiada. O estado vai em applicationStatus (e em detail).
watch_limit_reached 422 de watch_application: a org já tem o máximo de solicitações vigiadas ativas do seu plano; o máximo vai em limit.
watch_daily_limit_reached 429 de watch_application: a org esgotou os cadastros do dia (dia do Chile); traz limit e resetsAt (quando reabre), os dois no primeiro nível do corpo.
image_similarity_not_available 503 de find_similar_logos, operação futura declarada: NÃO é reprocessável (ao contrário de service_unavailable); não estará disponível até que uma entrada do changelog do contrato a anuncie.
out_of_coverage Pediu-se algo fora da cobertura declarada (um intervalo do calendário de feriados, o boletim de um dia, o texto de uma norma ou a versão de um documento, os indicadores). O erro traz coverage com o intervalo real.
internal_error Erro interno genérico — nunca vaza detalhes internos.

Detalhes internos do banco de dados ou do transporte nunca são incluídos na mensagem.

⭐ status é o do gêmeo REST: 401 para unauthorized, 403 para forbidden —com o mesmo detail que o REST, que nomeia o escopo que falta (API key lacks required scope: brands:read)—, 400 para validation_error, 404 para not_found —com o mesmo detail que o REST (trademark 123 not found…)—, 422 para out_of_coverage. Até 2026-09-28 o MCP dizia 400 para unauthorized e forbidden, e até 2026-09-29 também para not_found em 18 ferramentas; o code não mudou.

⭐ Desde 2026-09-30 (ERR-1) cada code tem um único status, o mesmo do REST, tirado de uma tabela única do código. Até essa data saíam com 400: query_timeout quando se esgotava o limite total da ferramenta (agora 504), watchlist_too_large e unsafe_callback (agora 422), idempotency_conflict (agora 409) e o service_unavailable do armazém de vigilâncias (agora 503). list_holidays sem calendário declarado dizia service_unavailable com 400; agora é coverage_not_declared com 503, como no REST. (watchlist_too_large, idempotency_conflict, concurrent_modification e watchlist_retired deixaram de existir em 2026-10-04 com as ferramentas de watchlists, e nenhuma ferramenta devolve mais unsafe_callback.)

Conecte seu cliente de IA

Cliente MCP Streamable-HTTP genérico

A maioria dos clientes MCP aceita uma entrada de servidor HTTP com headers personalizados. Aponte-o para o endpoint e envie sua chave no header X-API-Key:

{
  "mcpServers": {
    "tarno": {
      "type": "streamable-http",
      "url": "https://mcp.tarno.cl",
      "headers": { "X-API-Key": "<API_KEY>" }
    }
  }
}

Claude Desktop (via a ponte mcp-remote)

O Claude Desktop inicia servidores MCP sobre stdio, e sua UI embutida de conector personalizado só suporta servidores OAuth ou sem autenticação — não há campo para um header X-API-Key personalizado. Para alcançar um endpoint autenticado por header como o Tarno, faça uma ponte com o auxiliar mcp-remote, que roda localmente sobre stdio e injeta o header em cada requisição.

Pré-requisito: Node.js 18 ou mais novo no seu PATH (o Claude Desktop invoca npx). Verifique com node --version.

1. Abra seu arquivo de configuração do Claude Desktop (crie-o se ele não existir):

SO Caminho
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Você também pode chegar até ele por Settings → Developer → Edit Config.

2. Adicione o Tarno a mcpServers. Mantenha sua chave em uma entrada env (não inline em args) — este é o padrão seguro e evita um bug conhecido do Claude Desktop/Windows em que um espaço dentro de um valor de args é mal-escapado ao invocar npx:

{
  "mcpServers": {
    "tarno": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.tarno.cl",
        "--header", "X-API-Key:${TARNO_API_KEY}"
      ],
      "env": {
        "TARNO_API_KEY": "<API_KEY>"
      }
    }
  }
}

Substitua <API_KEY> pela chave emitida pelo seu operador. (Como uma chave de API nunca contém espaços, a forma inline "--header", "X-API-Key:<API_KEY>" também funciona — mas o padrão env acima mantém a chave fora da lista de args e evita o bug do espaço.)

3. Reinicie o Claude Desktop por completo (feche e reabra). O Tarno então aparece como uma fonte de ferramentas conectada; você pode pedir ao Claude que busque marcas ou obtenha o detalhe de uma marca, e ele chamará search_trademarks / get_trademark para você.

Solução de problemas: se o servidor não aparecer, confirme que node --version funciona em um terminal, que o JSON é válido (sem vírgulas sobrando) e que a chave é uma chave ativa e com escopo — um erro de ferramenta unauthorized/forbidden significa que a chave está ausente, inválida ou sem brands:read.

Para um cliente programático (connect + callTool) usando @modelcontextprotocol/sdk, veja os exemplos de código.

Veja também