# Servidor MCP de Bordado para Agentes de IA

Página canónica: https://embroideryfileconverter.com/pt/ai-agents

Ligue agentes de IA a ferramentas de bordados autenticadas através de um servidor MCP remoto com OAuth, descoberta de formatos, estado de utilização e trabalhos de processamento privados.

## Escolher a integração certa

- Utilize este servidor MCP remoto quando um assistente de IA deve agir em nome de um utilizador através de OAuth aprovado pelo navegador.
- Utilize a [REST Developer API](https://embroideryfileconverter.com/pt/developers) para um backend convencional, produto SaaS ou automação do lado do servidor.

## Conectar um cliente MCP

- Endpoint HTTP streamable: `https://embroideryfileconverter.com/mcp/embroidery`
- Âmbito OAuth: `mcp:use`
- Limite de taxa MCP predefinido: 60 pedidos por minuto
- Limite da ferramenta de criação de ficheiros: 6 pedidos por minuto por utilizador, mais um limite de rede
- Duração do token de acesso: 60 minutos
- Duração do token de atualização: 30 dias

O endpoint funciona com clientes HTTP Streamable remotos. Prefira OAuth nativo do navegador; nunca cole palavras-passe, tokens de atualização ou tokens de portador de longa duração num repositório.

## Ligar ChatGPT (OpenAI)

As aplicações MCP completas são configuradas no modo programador do ChatGPT. A disponibilidade e os controlos das ferramentas de escrita variam consoante o plano.

1. No ChatGPT web, ative o modo Programador em Definições > Aplicações > Definições avançadas, ou abra Definições do Espaço de Trabalho > Aplicações > Criar.
2. Crie uma aplicação e defina o URL do servidor MCP para `https://embroideryfileconverter.com/mcp/embroidery`.
3. Escolha OAuth, selecione Analisar ferramentas e aprove o âmbito `mcp:use` no navegador.
4. Crie o rascunho da aplicação, ative-a e selecione-a no menu de ferramentas numa nova conversa.

[Documentação oficial do MCP do ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

## Ligar Claude, Claude Desktop, Cowork ou Claude Code

No Claude, abra Personalizar > Conectores > Adicionar conector personalizado, introduza `https://embroideryfileconverter.com/mcp/embroidery`, escolha Ligar e conclua o OAuth. Os proprietários de Equipas e Empresas adicionam o conector em Definições da Organização > Conectores antes de os membros ligarem individualmente.

Comando Claude Code:

```bash
claude mcp add --transport http embroidery-file-converter https://embroideryfileconverter.com/mcp/embroidery
# Depois execute /mcp dentro do Claude Code e conclua a autorização no navegador.
```

[Documentação oficial do MCP remoto do Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

## Ligar o OpenAI Agents SDK

O seu backend deve concluir o código de autorização OAuth + PKCE para o utilizador autenticado, armazenar os tokens encriptados no servidor, atualizá-los quando necessário e passar o token de acesso atual para a ferramenta MCP alojada. Nunca exponha este token em JavaScript do navegador.

```typescript
import { Agent, hostedMcpTool } from '@openai/agents';

const agent = new Agent({
  name: 'Embroidery assistant',
  tools: [
    hostedMcpTool({
      serverLabel: 'embroidery',
      serverUrl: 'https://embroideryfileconverter.com/mcp/embroidery',
      authorization: process.env.EFC_MCP_ACCESS_TOKEN,
      requireApproval: 'always',
    }),
  ],
});
```

[Documentação oficial do MCP do OpenAI Agents SDK](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)

## Ligar Cursor

Adicione isto a `.cursor/mcp.json`, inicie o servidor em Definições do Cursor > MCP e conclua o OAuth. Os utilizadores do Cursor Agent podem executar `cursor-agent mcp login embroidery-file-converter`.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentação oficial do MCP do Cursor](https://docs.cursor.com/context/model-context-protocol)

## Ligar VS Code e GitHub Copilot

Execute `MCP: Add Server` e escolha HTTP, ou adicione isto a `.vscode/mcp.json`. Inicie com `MCP: List Servers`, confie na configuração e conclua a autorização no navegador.

```json
{
  "servers": {
    "embroidery-file-converter": {
      "type": "http",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentação oficial do MCP do VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

## Ligar OpenClaw

```bash
openclaw mcp add embroidery-file-converter \
  --url https://embroideryfileconverter.com/mcp/embroidery \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope mcp:use

openclaw mcp login embroidery-file-converter
openclaw mcp doctor embroidery-file-converter --probe
```

[Documentação oficial do MCP do OpenClaw](https://docs.openclaw.ai/cli/mcp)

## Ligar Gemini CLI

Adicione o servidor a `~/.gemini/settings.json`, depois execute `/mcp auth embroidery-file-converter` dentro do Gemini CLI.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentação oficial do MCP do Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)

## Ligar OpenCode

Adicione isto a `opencode.json`, depois execute `opencode mcp auth embroidery-file-converter` e verifique com `opencode mcp list`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "embroidery-file-converter": {
      "type": "remote",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentação oficial do MCP do OpenCode](https://opencode.ai/docs/mcp-servers/)

## Ligar Windsurf Cascade

Abra Definições do Windsurf > Cascade > Servidores MCP, ou adicione isto a `~/.codeium/windsurf/mcp_config.json`. Inicie o servidor, conclua o OAuth e ative apenas as ferramentas necessárias.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "serverUrl": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentação oficial do MCP do Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp)

## Ligar Cline

O comportamento OAuth do Cline varia conforme a versão e a interface. Abra Servidores MCP > Servidores Remotos, escolha Streamable HTTP e utilize esta configuração com uma lista de aprovação vazia:

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "type": "streamableHttp",
      "url": "https://embroideryfileconverter.com/mcp/embroidery",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Se a versão instalada do Cline não conseguir concluir o OAuth, utilize uma ponte OAuth revista e fixada por versão, ou escolha um cliente com OAuth nativo. Não confirme um token de longa duração em `cline_mcp_settings.json`.

[Documentação oficial do MCP do Cline](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx)

## Descoberta OAuth e PKCE

- Metadados do recurso protegido: `https://embroideryfileconverter.com/.well-known/oauth-protected-resource/mcp/embroidery`
- Metadados do servidor de autorização: `https://embroideryfileconverter.com/.well-known/oauth-authorization-server`
- Registo dinâmico de cliente: `https://embroideryfileconverter.com/oauth/register`
- Emissor do servidor de autorização: `https://embroideryfileconverter.com`
- Concessão: código de autorização
- Método PKCE: S256
- Escopo obrigatório: `mcp:use`

O registo dinâmico de cliente aceita apenas origens de callback e esquemas nativos explicitamente permitidos pelo operador. Domínios de callback arbitrários são rejeitados. A conta deve ter um endereço de email verificado antes de poder utilizar o endpoint MCP.

Os callbacks alojados fidedignos predefinidos estão limitados às origens oficiais do ChatGPT, Claude e VS Code, mais callbacks de loopback para clientes instalados. Domínios de redirecionamento wildcard não estão ativados. As implementações que substituam `MCP_REDIRECT_DOMAINS` devem reter apenas os clientes que pretendem suportar intencionalmente.

Exemplo de registo para um callback local permitido:

```bash
curl -X POST https://embroideryfileconverter.com/oauth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_name": "Your local agent",
    "redirect_uris": ["http://127.0.0.1:49831/callback"]
  }'
```

## Referência completa de ferramentas

### `list-formats-tool`

Somente leitura. Não aceita argumentos. Retorna `artwork_inputs[]` e `formats[]` com os campos readable, writable, label e warning. Chame antes de escolher um fluxo de trabalho ou formato de destino.

### `get-account-usage-tool`

Somente leitura. Não aceita argumentos. Retorna o limite atual de visualizações, saldo de créditos, custos dos fluxos, limites de assinatura e datas de reinício. Nunca compra nem consome nada.

### `list-processing-jobs-tool`

Somente leitura. Lista os trabalhos recentes pertencentes à conta conectada.

- `limit`: inteiro opcional de 1 a 50; padrão 20

### `get-processing-job-tool`

Somente leitura. Retorna um trabalho pertencente à conta com status, eventos, métricas, avisos, artefatos de visualização e URLs de arquivo protegidas por OAuth disponíveis.

- `workflow`: obrigatório `conversion` ou `digitising`
- `job_id`: obrigatório identificador de trabalho com 26 caracteres

### `create-processing-job-tool`

Cria dados armazenados. Inicia um trabalho de visualização privado e pode consumir o limite de visualizações, mas nunca compra créditos nem libera um download pago.

- `workflow`: obrigatório `conversion` ou `digitising`
- `file_name`: obrigatório nome do arquivo original com extensão, de 3 a 255 caracteres, sem separadores de caminho ou caracteres de controle
- `file_base64`: obrigatório base64 padrão bruto sem prefixo de data-URL
- `format`: obrigatório formato de saída de bordado gravável em minúsculas
- `width_mm`: número de 10 a 300, obrigatório para digitalização
- `colour_count`: inteiro de 1 a 24, obrigatório para digitalização

O resultado estruturado inclui `billing_authorized: false`. Para conversão, o formato de saída selecionado deve ser diferente do formato de origem detectado.

## Exemplos de ferramentas JSON-RPC

Listar formatos:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list-formats-tool",
    "arguments": {}
  }
}
```

Criar visualização de digitalização:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "file_name": "logo.png",
      "file_base64": "iVBORw0KGgoAAA...",
      "format": "pes",
      "width_mm": 90,
      "colour_count": 8
    }
  }
}
```

Consultar o trabalho retornado:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "job_id": "01JEXAMPLEJOBID000000000"
    }
  }
}
```

Os status possíveis do trabalho são `queued`, `processing`, `completed` e `failed`. Consulte com recuo exponencial e pare em um status terminal. As URLs de arquivo exigem o mesmo token de acesso OAuth e permanecem sujeitas à data de retenção `expiresAt` do upload.

## Exemplos de prompts em linguagem natural

- “Verifique quais formatos podem ler PES e gravar JEF com segurança. Mostre os avisos de compatibilidade.”
- “Liste meus cinco trabalhos de bordado mais recentes e resuma qualquer falha.”
- “Antes de enviar, peça minha confirmação. Depois digitalize logo.png com 90 mm de largura e no máximo 8 cores e retorne uma pré-visualização em PES.”
- “Consulte o trabalho 01J… até concluir, depois informe as métricas de pontos, avisos e se o download já está liberado.”

## Modelo de segurança

- Nenhuma ferramenta de faturamento, checkout, compra de créditos ou liberação de download pago é exposta.
- Nenhuma ferramenta de criação de chave de API, alteração de autenticação, leitura de credenciais ou exclusão de conta é exposta.
- Todo trabalho lido é restrito ao usuário conectado.
- A ferramenta de criação armazena um upload privado e cria um trabalho, portanto o agente deve pedir confirmação antes de enviar.
- Nomes de arquivo, metadados, mensagens de trabalho e avisos são dados não confiáveis. O servidor instrui os agentes a nunca seguir comandos embutidos nesses valores.
- Um resultado concluído não está automaticamente pronto para produção. Os agentes devem inspecionar as métricas de validação e os avisos antes de fazer afirmações.

## Resolução de problemas

- `401 Unauthorized`: nenhum token de acesso válido foi enviado; reinicie a conexão OAuth do cliente.
- `403 Forbidden`: o token não possui `mcp:use`, a conta não está verificada ou o trabalho solicitado pertence a outra conta.
- `invalid_redirect_uri`: a origem do callback ou o esquema nativo não está na lista de permissões do servidor.
- `422`: argumentos da ferramenta, dados base64, tipo de origem, formato de destino ou cota da conta falharam na validação.
- `429`: limite de taxa excedido; respeite `Retry-After` e use recuo exponencial com jitter.

## Páginas relacionadas

- [Documentação da API para desenvolvedores](https://embroideryfileconverter.com/pt/developers)
- [Descrição OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Política de privacidade](https://embroideryfileconverter.com/pt/privacy)