EduBase

Servidor MCP do EduBase

Este repositório contém a implementação do Model Context Protocol (MCP) do servidor da plataforma EduBase. Ele permite que clientes MCP (por exemplo, Claude Desktop) e LLMs interajam com sua conta EduBase e realizem tarefas em seu nome. Ele oferece suporte aos protocolos de transporte stdio, SSE e HTTP transmitível.

O que é o EduBase?

EduBase é uma plataforma educacional online inovadora e modular que torna o aprendizado mais agradável, simples e interativo, adequada para instituições de ensino ou empresas.

Por que escolher o EduBase?

EduBase revoluciona o aprendizado digital com sua combinação exclusiva de recursos:

• Sistema avançado de questionários com parametrização que permite variações infinitas da mesma pergunta, detecção de cola em tempo real, bela composição tipográfica em LaTeX, suporte avançado a STEM e correção automática
• Ambiente de aprendizagem unificado que centraliza todo o seu conteúdo educacional — vídeos, provas, documentos e módulos SCORM — em um sistema intuitivo
• Segurança de nível empresarial com recursos como integração SSO, controles de acesso granulares, auditoria abrangente e conformidade com o GDPR
• Integração com seus sistemas existentes por meio de LTI, API abrangente e opções de integração personalizadas
• Ferramentas assistidas por IA, como o EduBase Assistant, que podem transformar instantaneamente seu conteúdo existente em questionários e avaliações interativos ou traduzir seus materiais de um idioma para outro

De instituições de ensino superior a departamentos de treinamento corporativo, o EduBase se adapta às suas necessidades específicas, mantendo uma experiência intuitiva em todos os dispositivos.

Vídeo de demonstração

Criação colaborativa e envio de perguntas, agendamento de provas e análise dos resultados dos usuários com Claude:

Como obter suas credenciais de API

Depois de entrar, no seu Dashboard, procure o menu Integrations, clique em "add integration" e escolha o tipo "EduBase API".

Se você não vir essa opção, insira o código de ativação MCPGITHUB ou entre em contato conosco para solicitar acesso pelo endereço info@edubase.net.

Ferramentas

Cada endpoint de API documentado está disponível como uma ferramenta, denominada edubase_<method>_<endpoint>. Por exemplo, a ferramenta para o endpoint GET /user:me é denominada edubase_get_user_me. Os endpoints de tags, permissões e transferência funcionam da mesma forma para cada tipo de conteúdo, portanto, compartilham uma única ferramenta por método com um argumento type (por exemplo, edubase_post_content_tag para POST /exam:tag, POST /quiz:tag etc.). Consulte nossa documentação para desenvolvedores para obter mais informações.

Conjuntos de ferramentas

As ferramentas são agrupadas em conjuntos, para que você possa expor apenas as ferramentas necessárias. Menos ferramentas consomem menos contexto do modelo e facilitam a escolha da ferramenta certa. Todos os conjuntos de ferramentas são habilitados por padrão.

Conjunto de ferramentas	Ferramentas para
files	Envios temporários de arquivos (sempre habilitado)
questions	Perguntas
quizzes	Conjuntos de questionários, suas perguntas, configurações e predefinições de correção
exams	Provas, suas configurações, usuários, certificados, identidade visual e jornadas
results	Resultados de questionários e provas, downloads de certificados
users	Usuários, seus nomes, grupos e links de login
classes	Turmas e matrículas
organizations	Organizações, membros, departamentos, cargos, competências e webhooks
integrations	Integrações e suas chaves
tags	Tags e associações de tags a conteúdos
permissions	Permissões de usuários em conteúdos e transferências de propriedade
metrics	Métricas personalizadas

Selecione conjuntos de ferramentas com uma lista separada por vírgulas em EDUBASE_TOOLSETS (por exemplo, questions,quizzes,exams). Defina EDUBASE_READONLY=true para expor apenas as ferramentas que leem dados (as ferramentas get e as ferramentas que apenas geram links de download, como edubase_post_question_export).

Defina EDUBASE_DYNAMIC_TOOLSETS=true para habilitar conjuntos de ferramentas sob demanda: as sessões começam apenas com as ferramentas essenciais, e o modelo habilita os conjuntos de ferramentas necessários usando a ferramenta edubase_enable_toolsets (listada com edubase_list_toolsets). Isso mantém pequena a lista inicial de ferramentas para clientes que carregam todas as ferramentas antecipadamente, mas requer um cliente que atualize a lista de ferramentas quando for notificado sobre alterações.

Quando um transporte HTTP é usado, os clientes podem restringir ainda mais a configuração para sua própria sessão com os cabeçalhos EduBase-Mcp-Toolsets, EduBase-Mcp-ReadOnly e EduBase-Mcp-Dynamic, ou os parâmetros de consulta toolsets, read_only e dynamic_toolsets (por exemplo, https://domain.edubase.net/mcp?toolsets=exams&read_only=true). Uma sessão nunca pode habilitar conjuntos de ferramentas ou ferramentas de escrita desabilitados pela configuração do servidor.

Prompts

Os prompts são fluxos de trabalho prontos para uso que você pode iniciar no seu cliente MCP (por exemplo, no menu + ou /). Clientes compatíveis com preenchimento sugerem valores para os argumentos enquanto você digita: tipos de pergunta e suas próprias provas, conjuntos de questionários e turmas.

Prompt	O que faz	Argumentos
Criar uma pergunta (edubase_prompt_create_question)	Cria uma nova pergunta e a publica na sua QuestionBase	type, subject, opcionais difficulty e language
Criar perguntas a partir de um documento (edubase_prompt_questions_from_document)	Transforma um documento anexado (ou um caminho de arquivo ou URL) em perguntas, após sua aprovação do plano, adicionando-as opcionalmente a um conjunto de questionários	document, opcional questions (quantidade), types, quiz e language
Criar uma prova (edubase_prompt_create_exam)	Gera perguntas sobre um tópico, reúne-as em um novo conjunto de questionários e cria uma prova a partir dele	topic, questions (quantidade), opcionais types (separados por vírgulas), language e schedule
Criar uma prova com uma jornada (edubase_prompt_create_exam_journey)	Cria uma prova como acima e, em seguida, cria e publica uma pequena jornada de provas a partir dela, reutilizando provas relacionadas da sua conta e criando um conjunto de questionários de prática e uma prova de acompanhamento, se necessário	os mesmos de Criar uma prova
Copiar uma prova (edubase_prompt_copy_exam)	Cria uma nova prova com o mesmo conjunto de questionários e as mesmas configurações, para um novo período	exam, schedule, opcional title
Atribuir uma turma a uma prova (edubase_prompt_assign_class_to_exam)	Atribui os membros ativos de uma turma a uma prova	exam, class
Resumir os resultados de uma prova (edubase_prompt_summarize_exam_results)	Analisa os resultados de uma prova e, opcionalmente, salva o resumo na prova	exam, opcionais focus e save (ask, yes ou no)
Verificar uma jornada de provas (edubase_prompt_exam_journey_status)	Mostra o progresso dos usuários em uma jornada de provas e quem está com dificuldades	exam

Os prompts só são oferecidos quando seus conjuntos de ferramentas estão habilitados; no modo somente leitura, apenas os dois últimos são oferecidos.

Quando os tipos de pergunta de uma prova não são especificados, clientes compatíveis com elicitação solicitam que você os escolha usando caixas de seleção. Esses clientes também pedem que você confirme as alterações irreversíveis (exclusão de provas, conjuntos de questionários, perguntas, usuários, organizações e integrações; transferência de propriedade; início de uma nova rodada de prova; e rotação de chaves de integração) antes de realizá-las. Defina EDUBASE_ELICITATION=false para desativar essas perguntas.

Recursos

Documentos de referência estão disponíveis como recursos e pela ferramenta edubase_mcp_reference para modelos que não conseguem ler recursos: edubase://reference/questions (os campos e tipos de pergunta) e edubase://reference/exam-journeys (o formato portátil de jornada de provas). Eles abrangem o que as habilidades do EduBase explicam, para clientes sem essas habilidades. Provas e conjuntos de questionários também podem ser anexados como recursos (edubase://exam/{exam} e edubase://quiz/{quiz}), com seus conteúdos listados e sugeridos. Desative-os com EDUBASE_CONTENT_RESOURCES=false ou, para uma sessão, com o cabeçalho EduBase-Mcp-Content-Resources: false, o parâmetro de consulta content_resources=false ou a configuração do Smithery edubaseContentResources.

As ferramentas que criam ou alteram provas, conjuntos de questionários e jornadas incluem links para suas páginas no EduBase.

Configuração

O servidor MCP pode ser configurado usando variáveis de ambiente. As seguintes variáveis estão disponíveis:

Variável	Descrição	Obrigatório	Valor padrão
EDUBASE_API_URL	A URL base da API do EduBase, provavelmente https://subdomain.edubase.net/api.	Sim	https://www.edubase.net/api
EDUBASE_API_APP	O ID do app de integração no EduBase, o app na API do EduBase. Encontre-o na janela de detalhes da integração no EduBase.	Não, se o transporte HTTP for usado com autenticação; caso contrário, Sim	-
EDUBASE_API_KEY	A chave secreta do app de integração no EduBase, o secret na API do EduBase. Encontre-a junto ao ID do app na janela de detalhes da integração no EduBase.	Não, se o transporte HTTP for usado com autenticação; caso contrário, Sim	-
EDUBASE_SSE_MODE	Inicia o servidor MCP no modo HTTP com transporte SSE. O valor deve ser true.	Não	false
EDUBASE_STREAMABLE_HTTP_MODE	Inicia o servidor MCP no modo HTTP com transporte HTTP transmitível. O valor deve ser true.	Não	false
EDUBASE_TOOLSETS	Lista separada por vírgulas dos conjuntos de ferramentas habilitados, ou all.	Não	all
EDUBASE_READONLY	Expõe somente as ferramentas que leem dados. O valor deve ser true.	Não	false
EDUBASE_OUTPUT_SCHEMAS	Esquemas de saída das ferramentas e resultados estruturados das ferramentas: off lista as ferramentas sem esquemas de saída e retorna os resultados somente como texto JSON; on inclui os esquemas de saída completos; fields inclui os esquemas de saída sem as descrições dos campos (mantendo os resultados estruturados, mas economizando a maior parte dos tokens dos esquemas).	Não	fields
EDUBASE_CONFIG_PROVIDERS	Lista separada por vírgulas dos provedores de hospedagem autorizados a fornecer a configuração da sessão nas solicitações quando um transporte HTTP é usado. Atualmente, somente smithery é compatível (o parâmetro de consulta config codificado em base64).	Não	-
EDUBASE_CONTENT_RESOURCES	Lista os exames e conjuntos de Quiz da conta como recursos. Defina como false para desativá-los, por exemplo, quando o servidor for inspecionado sem credenciais. Os documentos de referência continuam disponíveis.	Não	true
EDUBASE_DYNAMIC_TOOLSETS	Inicia sessões somente com as ferramentas de upload de arquivos e permite que o modelo habilite conjuntos de ferramentas sob demanda. O valor deve ser true.	Não	false
EDUBASE_ELICITATION	Solicita ao usuário, por meio do cliente, que confirme as alterações irreversíveis e escolha os tipos de pergunta dos prompts, se o cliente oferecer suporte à elicitação. Defina como false para desativar.	Não	true
EDUBASE_HTTP_PORT	O servidor HTTP escutará nesta porta se o modo de transporte SSE ou HTTP transmitível for usado.	Não	3000
EDUBASE_OAUTH	Habilita o comportamento de recurso protegido do OAuth 2.1: solicitações não autenticadas são rejeitadas com 401 + WWW-Authenticate apontando para /.well-known/oauth-protected-resource/mcp, e os tokens bearer são encaminhados à API do EduBase.	Não	false
EDUBASE_OAUTH_AUTHORIZATION_SERVER	URL base pública da implantação do EduBase que atua como IdP do OAuth. Usada para anunciar o servidor de autorização no documento de metadados do recurso protegido.	Não	derivada de EDUBASE_API_URL
EDUBASE_OAUTH_RESOURCE_URL	URL base pública deste servidor MCP (o indicador de recurso OAuth). Usada no cabeçalho WWW-Authenticate e nos metadados do recurso.	Não	derivada de EDUBASE_API_URL
EDUBASE_ALLOW_PRIVATE_NETWORK	Quando um transporte HTTP é usado, a ferramenta edubase_filebin bloqueia solicitações de saída para endereços privados, de loopback, de link local e reservados (proteção contra SSRF) e recusa caminhos de arquivos locais. Defina como true para permiti-los, por exemplo, em uma implantação auto-hospedada em uma rede privada confiável. Não tem efeito no modo stdio, em que o usuário local é o único solicitante.	Não	false
EDUBASE_FILEBIN_ALLOWED_HOSTS	Lista de permissões opcional, separada por vírgulas, de nomes de host permitidos como destinos de upload edubase_filebin (host exato ou qualquer subdomínio, por exemplo, edubase.net). Quando vazia, qualquer host público é permitido (ainda sujeito à filtragem de endereços acima).	Não	-

Usar como servidor MCP remoto

Você pode usar o servidor MCP do EduBase como servidor MCP remoto para seu cliente MCP. Para isso, hospede o servidor em um local acessível aos clientes e configure o cliente para se conectar a ele. Inicie-o no modo de transporte SSE ou HTTP transmitível e sempre use HTTPS ao acessar o servidor remotamente pela internet!

Autenticação com servidores remotos

Você pode usar o servidor em dois modos:

• Sem autenticação do cliente: nesse modo, o servidor não exigirá autenticação do cliente. Isso é útil para testes ou desenvolvimento, ou em uma rede fechada, mas não é recomendado para uso em produção. Para isso, você também precisa configurar o servidor com EDUBASE_API_APP e EDUBASE_API_KEY!
• Com autenticação por token Bearer: nesse modo, o servidor exigirá o envio de um token Bearer em cada solicitação. Esta é a forma recomendada de usar o servidor em produção. Você pode obter o token Bearer na sua conta do EduBase criando um app de integração e fornecendo o ID do app e a chave secreta no formato {app}:{secret}, codificado em base64 como token. O servidor usará esse token para autenticar o cliente e autorizar o acesso aos endpoints da API.
• Com OAuth 2.1 (EduBase como IdP): quando EDUBASE_OAUTH=true, os clientes compatíveis (Claude Desktop, conectores do Claude.ai, Cursor, conectores do ChatGPT etc.) descobrem o servidor de autorização do EduBase por meio de /.well-known/oauth-protected-resource, registram-se dinamicamente (RFC 7591), orientam o usuário pela tela de consentimento do EduBase e trocam um código de autorização (com PKCE S256) por um token de acesso opaco. O servidor MCP encaminha esse token sem alterações à API do EduBase, que o associa à integração MCP provisionada automaticamente, criada no primeiro consentimento. Não é necessário copiar o ID do app nem a chave secreta — os usuários só precisam clicar em "Conectar ao EduBase" no cliente.

Uso com o Claude Desktop

Para ver um passo a passo, consulte nossa publicação no blog sobre como conectar o EduBase ao Claude: o guia completo de integração MCP.

Usar o servidor MCP do EduBase fornecido

Você pode usar o servidor MCP do EduBase fornecido (se disponível) sem nenhuma configuração, basta adicioná-lo como servidor remoto no cliente com a URL https://domain.edubase.net/mcp (substitua pelo domínio real), se houver suporte à autenticação OAuth, ou com o token Bearer apropriado no cabeçalho Authorization (Authorization: Bearer ${BASE64_ENCODED_TOKEN}).

Recomendado para usuários de www.edubase.net, pois o servidor é mantido e atualizado por nós, e você não precisa se preocupar com hospedagem ou configuração. Basta usar a URL e o método de autenticação corretos ao conectar o cliente.

Instalação manual

Adicione o seguinte ao seu claude_desktop_config.json:

Usando Node.js

Antes de executar o servidor MCP, verifique se o Node.js está instalado. Você pode baixá-lo em nodejs.org ou usar um gerenciador de pacotes como brew.

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "-y",
        "@edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Ou baixe uma versão do servidor MCP do EduBase ou clone o repositório e execute npm run build para compilar o servidor. Não se esqueça de ajustar /path/to/dist para o diretório real e configurar as variáveis de ambiente!

{
  "mcpServers": {
    "edubase": {
      "command": "node",
      "args": [
        "/path/to/dist/index.js"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Usando Docker

Antes de executar o servidor MCP, verifique se o Docker está instalado e em execução. Você pode baixá-lo em docker.com ou usar um gerenciador de pacotes. Não se esqueça de configurar as variáveis de ambiente! A imagem está disponível para linux/amd64 e linux/arm64 no Docker Hub como edubase/mcp e no GitHub Packages como ghcr.io/edubase/mcp.

{
  "mcpServers": {
    "edubase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "EDUBASE_API_URL",
        "-e",
        "EDUBASE_API_APP",
        "-e",
        "EDUBASE_API_KEY",
        "edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Instalação via servidor MCP remoto

Você pode usar o servidor MCP do EduBase fornecido (se disponível) como servidor remoto. Recomendamos codificar em Base64 seu EDUBASE_API_APP e EDUBASE_API_KEY e usá-lo como token Bearer no cabeçalho Authorization (Authorization: Bearer ${BASE64_ENCODED_TOKEN}).

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://domain.edubase.net/mcp",
        "--header",
        "Authorization: Bearer ${EDUBASE_API_APP}:${EDUBASE_API_KEY}"
      ]
    }
  }
}

Instalação via Smithery

Para instalar automaticamente o servidor MCP do EduBase para o Claude Desktop via Smithery:

npx -y @smithery/cli install @EduBase/MCP --client claude

Desenvolvimento

Execute npm test para compilar o servidor e verificar a listagem de ferramentas: os limites de tamanho da lista de ferramentas e das instruções do servidor, as descrições das ferramentas, os modos de conjuntos de ferramentas, somente leitura e conjuntos de ferramentas dinâmicos, e o tratamento da configuração do transporte HTTP. Quando novas ferramentas ultrapassarem um limite, encurte seus esquemas ou aumente deliberadamente o limite em test/server.test.mjs, pois cada cliente paga pelo custo da lista de ferramentas em todas as sessões.

Os documentos de referência em src/references são gerados a partir da documentação para desenvolvedores do EduBase. Gere-os novamente com node scripts/sync-references.mjs <path to the developer documentation repository> quando os campos das perguntas ou o formato do fluxo de exames forem alterados.

A mesclagem de uma solicitação de pull rotulada como major, minor ou patch confirma a próxima versão em main e inicia o fluxo de trabalho Publish, que publica o pacote no npm e no MCP Registry e a imagem de contêiner no Docker Hub e no GitHub Packages, além de marcar o commit e criar uma versão do GitHub quando tudo tiver sido concluído com sucesso. Sem um desses rótulos, nada é publicado. Uma versão definida manualmente na solicitação de pull é publicada como está. O commit, a tag e a versão são criados por um app de publicação dedicado, cujas credenciais estão no ambiente release. O fluxo de trabalho Publish executa os testes primeiro, verifica a imagem compilada antes de enviá-la e autentica no Docker Hub com OIDC, usando as variáveis DOCKERHUB_OIDC_CONNECTIONID e DOCKERHUB_OIDC_USERNAME. Ele envia para o GitHub Packages usando o GITHUB_TOKEN do job, pois o GitHub não aceita tokens de GitHub App nesse serviço. Execute-o manualmente com uma versão para tentar novamente ou reconstruir uma publicação: o que já estiver no npm e no MCP Registry será ignorado, e latest só avança para a versão mais recente.

Ponto de sincronização da documentação: ferramentas, prompts e referências sincronizados pela última vez em 2026-11-06 com a Documentação para desenvolvedores sincronizada com a versão do EduBase 8.6.6 (a solicitação de pull da documentação para desenvolvedores 8.6.6), verificada em relação ao EduBase no commit a29c6af51. Para atualizar o servidor, execute git log --oneline <commit>..HEAD e git diff <commit>..HEAD -- docs/api/endpoints no repositório da documentação para desenvolvedores, a partir do commit da solicitação de pull da documentação 8.6.6, atualize as ferramentas afetadas em src/tools (e seus prompts e guias de conjuntos de ferramentas), gere novamente os documentos de referência e atualize este marcador para os novos commits HEAD. Quando houver divergências, prevalece o repositório do EduBase.

Contato

Site: www.edubase.net
Documentação para desenvolvedores: developer.edubase.net
E-mail: info@edubase.net