Conecte seu agente de IA (MCP)

O IRIS traz um servidor MCP neutro e somente leitura para que um agente de IA possa consultar o corpus de marcas do INAPI através do Model Context Protocol. Ele expõe o mesmo contrato de leitura da API REST — apoiado na mesma camada de consultas e nos mesmos schemas Zod — de modo que os dois transportes retornam resultados idênticos.

Endpoint e transporte

Propriedade	Valor
Endpoint	`https://mcp.obviouy.com`
Transporte	Streamable HTTP (MCP)
Autenticação	Header `X-API-Key`, enviado por requisição
Identidade do servidor	`iris-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.

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 iris_xxx nesta documentação):

X-API-Key: iris_xxx

Ambas as ferramentas exigem o escopo brands:read (uma chave irrestrita, de escopo vazio, também funciona) — 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.

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

{ "error": { "code": "quota_exceeded", "message": "Monthly quota exceeded", "requestId": "..." } }

Catálogo de ferramentas

O servidor registra exatamente duas ferramentas somente leitura.

`search_brands`

Busca no corpus de marcas neutro por texto livre (full-text + fuzzy) com filtros opcionais e paginação por keyset estável. Idêntico ao REST GET /v1/brands.

Entrada (o formato de busca compartilhado — todos os campos opcionais):

Campo	Tipo	Notas
`q`	string	Consulta por texto livre. Quando presente, os resultados são ranqueados.
`clase`	integer	Classe de Nice, `1`–`45`.
`estado`	string	Código de status (catálogo controlado).
`tipoSigno`	string	Código de tipo de signo (catálogo controlado).
`fechaDesde`	`YYYY-MM-DD`	Limite inferior da data de apresentação.
`fechaHasta`	`YYYY-MM-DD`	Limite superior da data de apresentação.
`limit`	integer	Tamanho da página, padrão `20`, máx. `100`.
`cursor`	string	Cursor de keyset opaco para a próxima página.

Saída: uma página JSON de resumos de marcas — { items: [...], nextCursor: string | null } — idêntica ao REST GET /v1/brands. O payload é retornado como o primeiro bloco de conteúdo de texto do resultado da ferramenta (faça o parse como JSON).

`get_brand_detail`

Busca uma marca pelo seu número de solicitação, composta com suas classes, pessoas (com papel) e anotações do Estado-Diário. Idêntico ao REST GET /v1/brands/:nroSolicitud.

Entrada:

Campo	Tipo	Notas
`nroSolicitud`	string	O número de solicitação da marca (obrigatório).

Saída: o detalhe completo da marca como JSON, ou null quando o número de solicitação é desconhecido. (O equivalente REST retorna 404 not_found para um número desconhecido; a ferramenta retorna null.)

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": {
    "iris": {
      "type": "streamable-http",
      "url": "https://mcp.obviouy.com",
      "headers": { "X-API-Key": "iris_xxx" }
    }
  }
}

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 IRIS, 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 IRIS 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": {
    "iris": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.obviouy.com",
        "--header", "X-API-Key:${IRIS_API_KEY}"
      ],
      "env": {
        "IRIS_API_KEY": "iris_xxx"
      }
    }
  }
}

Substitua iris_xxx pela chave emitida pelo seu operador. (Como uma chave de API nunca contém espaços, a forma inline "--header", "X-API-Key:iris_xxx" 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 IRIS 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_brands / get_brand_detail 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

Autenticação e escopos — X-API-Key, brands:read, ciclo de vida, códigos de erro.
Exemplos de código — um cliente mínimo do SDK MCP.
Primeiros passos — os primeiros passos REST equivalentes.