Servidor MCP

O servidor Model Context Protocol do seven permite que assistentes de IA como Claude Desktop, Claude Code e Cursor interajam diretamente com a API do seven.io. Ele expõe SMS, RCS, voz, consultas, contatos e gerenciamento de conta como mais de 40 ferramentas em 12 categorias.

Você tem duas maneiras de conectar o servidor:

• Servidor hospedado (URL) - conexão direta a https://mcp.seven.io/mcp sem qualquer instalação. Transporte Streamable HTTP, login OAuth automático no navegador.
• Instalação local (npx) - o pacote npm @seven.io/mcp executado via npx sobre o transporte stdio do MCP. O código-fonte está disponível no GitHub.

Servidor hospedado (URL)

Adicione a URL https://mcp.seven.io/mcp ao seu cliente MCP. O servidor usa o transporte Streamable HTTP (não SSE) e OAuth 2.0 com PKCE via descoberta do servidor de autorização.

Claude Code

claude mcp add --transport http seven https://mcp.seven.io/mcp

Cursor

Adicione o servidor ao arquivo .cursor/mcp.json do seu projeto:

{
  "mcpServers": {
    "seven": {
      "url": "https://mcp.seven.io/mcp"
    }
  }
}

Claude Desktop

A maneira mais simples é pela interface: Configurações → Connectors → Add custom connector, insira a URL https://mcp.seven.io/mcp. O Claude então abre o login OAuth no navegador.

Como alternativa, adicione o trecho ao claude_desktop_config.json usando a ponte mcp-remote:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.seven.io/mcp"]
    }
  }
}

Autenticação

Na primeira conexão, o cliente MCP descobre automaticamente o endpoint OAuth, abre o navegador, solicita os escopos necessários (SMS, Voz, RCS, …) e armazena os tokens. Nenhum passo de login manual é necessário.

Instalação local (npx)

O pacote npm @seven.io/mcp é iniciado pelo seu cliente MCP via npx. Não é necessária uma instalação global - npx baixa a versão mais recente sob demanda. Se desejar mesmo assim:

npm install -g @seven.io/mcp

Claude Code

claude mcp add seven npx @seven.io/mcp

Cursor

Adicione o servidor ao arquivo .cursor/mcp.json do seu projeto:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"]
    }
  }
}

Claude Desktop

Edite seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"]
    }
  }
}

Autenticação

A variante local suporta dois métodos. Recomenda-se OAuth 2.0 com PKCE - renovação automática de tokens, escopos refinados e armazenamento seguro dos tokens no chaveiro do sistema operacional. Se ambos os métodos estiverem configurados, o OAuth tem prioridade.

OAuth 2.0 (recomendado)

Execute o comando de login uma vez. Ele abre o navegador, solicita os escopos necessários e armazena os tokens.

npx @seven.io/mcp login

Outros comandos CLI:

# Mostrar se você está autenticado
npx @seven.io/mcp status

# Remover os tokens armazenados
npx @seven.io/mcp logout

Chave de API (legado)

Defina a variável de ambiente SEVEN_API_KEY. Crie sua chave no painel do seven.io.

export SEVEN_API_KEY="sua-chave-api"

Na configuração do cliente:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "sua-chave-api"
      }
    }
  }
}

Configurações headless ou remotas

O fluxo de login OAuth precisa de um navegador na mesma máquina que consiga acessar 127.0.0.1:7177 / 9437 / 8659. Se você executar o servidor MCP em um sistema sem interface gráfica ou via SSH sem encaminhamento de portas, use o servidor hospedado (URL) ou a variante com chave de API - ambos os caminhos funcionam sem um navegador local.

Ferramentas disponíveis

O servidor fornece mais de 40 ferramentas agrupadas por funcionalidade.

Mensagens

Conta

Consultas

Status e diário

Números de telefone

Contatos

Grupos

Subcontas

Webhooks

Remetente

Exemplos

Quando o servidor estiver conectado, você pode pedir ao assistente em linguagem natural. O cliente MCP escolhe a ferramenta certa automaticamente.

Enviar um SMS:

Envie um SMS para +49170123456789 com o texto 'Pedido enviado, acompanhe em example.com/t/abc123'.

O assistente chama send_sms.

Consultar o saldo:

Qual é o saldo da minha conta seven.io?

O assistente chama get_balance.

Preços por país:

Quanto custa um SMS para a França, a Espanha e os Estados Unidos?

O assistente chama get_pricing e filtra os resultados.

Consulta de operadora e verificação de RCS:

Procure a operadora do +49170123456789 e me diga se o número suporta RCS.

O assistente encadeia lookup_mnp e lookup_rcs.

Verificar disponibilidade e enviar:

Verifique via HLR se +49170123456789 está acessível. Se sim, envie um SMS com o texto 'Reunião amanhã às 10h'.

O assistente chama lookup_hlr e decide com base no resultado se executa send_sms.

Criar uma subconta e transferir saldo:

Crie uma subconta para nossa nova equipe e transfira 50 EUR de saldo para ela.

O assistente encadeia create_subaccount e transfer_credits.

Solução de problemas

Registro de depuração

Defina SEVEN_LOG_FILE para registrar cada requisição e resposta da API em um arquivo. Útil quando uma chamada de ferramenta não se comporta como esperado.

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "sua-chave-api",
        "SEVEN_LOG_FILE": "/tmp/mcp-seven-debug.log"
      }
    }
  }
}

Em seguida, acompanhe o arquivo de log:

tail -f /tmp/mcp-seven-debug.log

Recursos

• Repositório no GitHub
• Pacote npm
• Especificação do Model Context Protocol
• Rastreador de issues