Como Criar um Servidor MCP com o SDK Java

Olá, entusiastas de Java! Gostaria de turbinar seus projetos de IA com um Servidor MCP Java personalizado? O Protocolo de Contexto de Modelo (MCP) permite que modelos de IA como Claude ou Cursor acessem seus dados com facilidade, e com o SDK Java, você pode construir um servidor leve para que isso aconteça. Neste tutorial, criaremos um Servidor MCP Java para compartilhar dados de apresentação com assistentes de IA. Manteremos a abordagem divertida, conversacional e amigável para iniciantes, guiando você pela configuração, testes e extensão do seu servidor. Vamos mergulhar!

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e completa para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!

button

O Que É um Servidor MCP Java?

Um Servidor MCP Java é uma aplicação Java elegante que usa o Protocolo de Contexto de Modelo (MCP) para expor dados a modelos de IA. É como dar à sua IA um passe VIP para as informações do seu aplicativo — o nosso compartilhará dados de jogos, mas você pode personalizá-lo para qualquer coisa. O servidor usa o SDK Java do MCP para criar ferramentas que assistentes de IA podem chamar, como buscar uma lista de jogos ou pesquisar um por título. É perfeito para integrar seus dados com clientes de IA, e é super fácil de configurar com Spring Boot e Maven.

Guia Passo a Passo para Criar um Servidor MCP Java

Pré-requisitos

Antes de começarmos, certifique-se de ter:

Java 24: Baixe em oracle.com.
Maven 3.8+: Instale em maven.apache.org.
IntelliJ IDEA: Obtenha em jetbrains.com (ou sua IDE preferida).
Node.js: Para testes com o MCP Inspector (nodejs.org).
Claude Desktop ou Cursor: Opcional, para integração de IA (anthropic.com ou cursor.sh).

Passo 1: Criar ou Clonar o Projeto

Você pode clonar um repositório existente ou criar um projeto do zero.

Opção 1: Clonar o Repositório (Recomendado)

1. Em um novo terminal, execute:

git clone https://github.com/danvega/javaone-mcp.git
cd javaone-mcp

2. Construir o Projeto:

Use o Maven para criar um JAR executável:

mvn clean package

Encontre o JAR em target/javaone-mcp-0.0.2.jar.

Opção 2: Criar do Zero

1. Abra o IntelliJ IDEA:

Selecione New Project (Novo Projeto).
Escolha Maven como sistema de build.
Defina o nome do projeto (ex: java-mcp-server) e clique em Create (Criar).

2. Adicionar Dependências:

Abra pom.xml e adicione:

<dependencies>
  <!-- MCP SDK -->
  <dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>0.9.0</version>
  </dependency>
  <!-- Logging -->
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.16</version>
  </dependency>
  <dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.16</version>
  </dependency>
</dependencies>

Passo 2: Entendendo a Estrutura do Projeto

O Servidor MCP Java que acabamos de clonar inclui:

Application.java: O ponto de entrada principal que inicia o servidor MCP.
Presentation.java: Um modelo de dados para dados de jogos (vamos personalizá-lo para jogos).
PresentationTools.java: Define ferramentas MCP para acessar dados de jogos.
Configuração: Usa transporte STDIO para comunicação de IA.

Passo 3: Definir o Modelo de Dados

Crie Presentation.java para representar dados de jogos:

public record Presentation(String title, String url) { }

Este registro contém detalhes do jogo como título (ex: “GTA 6”) e URL.

Passo 4: Implementar Ferramentas MCP

Em PresentationTools.java, defina ferramentas usando o SDK do MCP:

import io.modelcontextprotocol.sdk.McpSchema;
import java.util.ArrayList;
import java.util.List;

public class PresentationTools {
    private final List<Presentation> presentations = new ArrayList<>();

    public PresentationTools() {
        presentations.add(new Presentation("GTA 6", "https://example.com/gta6"));
        presentations.add(new Presentation("FC 26", "https://example.com/fc26"));
        presentations.add(new Presentation("Call of Duty: Black Ops 7", "https://example.com/codbo7"));
    }

    @McpSchema.Tool(name = "get_presentations", description = "Returns a list of all available games")
    public List<Presentation> getPresentations() {
        return presentations;
    }

    @McpSchema.Tool(name = "get_game", description = "Returns a specific game by title")
    public Presentation getGame(String title) {
        return presentations.stream()
            .filter(p -> p.title().equalsIgnoreCase(title))
            .findFirst()
            .orElse(null);
    }
}

Essas ferramentas permitem que modelos de IA busquem todos os jogos ou um jogo específico por título.

Passo 5: Configurar e Iniciar o Servidor MCP

Em Application.java, configure o Servidor MCP Java:

import io.modelcontextprotocol.sdk.McpServer;
import io.modelcontextprotocol.sdk.McpSchema;
import io.modelcontextprotocol.sdk.McpSyncServer;

public class Application {
    public static void main(String[] args) {
        PresentationTools tools = new PresentationTools();
        var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
            new McpSchema.Tool("get_presentations", "Returns a list of all available games", null),
            (exchange, arguments) -> tools.getPresentations()
        );

        McpSyncServer syncServer = McpServer.sync(new StdioTransportProvider())
            .serverInfo("javaone-mcp-server", "0.0.1")
            .capabilities(McpSchema.ServerCapabilities.builder()
                .tools(true)
                .logging()
                .build())
            .tools(syncToolSpecification)
            .build();

        syncServer.start();
    }
}

Isso configura o servidor para usar o transporte STDIO e registra a ferramenta get_presentations.

Passo 6: Executar o Servidor MCP Java

1. Construir o Projeto:

Execute:

mvn clean package

2. Iniciar o Servidor:

Execute o JAR:

java -jar target/javaone-mcp-0.0.2.jar

O servidor é executado com transporte STDIO, pronto para integração de IA.

Passo 7: Testar com o MCP Inspector

Use o MCP Inspector para depurar seu Servidor MCP Java:

Instalar Node.js: Baixe em nodejs.org se necessário.

Obter o Caminho do JAR:

Linux/macOS:

FULL_PATH=$(pwd)/target/javaone-mcp-0.0.2.jar
echo $FULL_PATH

Windows PowerShell:

$FULL_PATH="$(Get-Location)\target\javaone-mcp-0.0.2.jar"
echo $FULL_PATH

Executar MCP Inspector:

Use:

npx @modelcontextprotocol/inspector java -jar $FULL_PATH

No Inspector:
Verifique a conexão no painel Connection (Conexão).
Vá para a aba Tools (Ferramentas), selecione get_presentations e visualize a resposta (ex: “GTA 6, FC 26, Call of Duty: Black Ops 7”).
Monitore os logs no painel Notifications (Notificações).

Passo 8: Integrar com Claude Desktop ou Cursor

Conecte seu Servidor MCP Java a um cliente de IA:

Obter o Caminho do JAR: Use o mesmo comando acima.

a. Configurar Claude Desktop:

Abra claude_desktop_config.json (macOS: ~/Library/Application Support/Claude, Windows: %APPDATA%\Claude).
Adicione:

{
  "mcpServers": {
    "javaone-mcp": {
      "command": "java",
      "args": ["-jar", "FULL_PATH"]
    }
  }
}

Substitua FULL_PATH pelo caminho do seu JAR.

b. Configurar Cursor:

Vá para Settings > Cursor Settings > Tools and Integrations > New MCP Server (Configurações > Configurações do Cursor > Ferramentas e Integrações > Novo Servidor MCP).
Adicione a mesma configuração e salve.

Reiniciar o Cliente: Feche e reabra o Claude ou Cursor.

Passo 9: Testar o Servidor MCP Java

Teste com Claude Desktop ou Cursor:

Iniciar o Servidor:

Execute:

java -jar target/javaone-mcp-0.0.2.jar

Emitir um Comando:

No Claude ou Cursor, digite:

Usando o servidor MCP, obtenha todos os jogos disponíveis.

Resposta esperada:

Os jogos disponíveis são GTA 6, FC 26 e Call of Duty: Black Ops 7.

Passo 10: Estender o Servidor MCP Java

Deixe seu servidor ainda mais legal:

1. Adicionar Mais Apresentações:

Em PresentationTools.java, adicione ao construtor:

presentations.add(new Presentation("Spring Boot 3.5 Deep Dive", "https://example.com/spring-boot", 2025));

2. Criar uma Ferramenta de Busca:

Adicione a PresentationTools.java:

@McpSchema.Tool(name = "search_presentations", description = "Search presentations by title")
public List<Presentation> searchPresentations(String query) {
    return presentations.stream()
        .filter(p -> p.title().toLowerCase().contains(query.toLowerCase()))
        .collect(Collectors.toList());
}

Registre em Application.java:

var searchToolSpec = new McpServerFeatures.SyncToolSpecification(
    new McpSchema.Tool("search_presentations", "Search presentations by title", null),
    (exchange, arguments) -> {
        String query = arguments.get("query").asText();
        return tools.searchPresentations(query);
    }
);
McpSyncServer syncServer = McpServer.sync(new StdioTransportProvider())
    .serverInfo("javaone-mcp-server", "0.0.1")
    .capabilities(McpSchema.ServerCapabilities.builder().tools(true).logging().build())
    .tools(syncToolSpecification, searchToolSpec)
    .build();

Personalizei meu servidor MCP para trabalhar com dados de jogos. E aqui estão meus resultados:

Experimentar uma Busca:

Adicionei uma ferramenta search_games (veja abaixo) e tentei o seguinte prompt:

Buscar um jogo com o título "FC".

Resposta esperada:

Você tem um jogo intitulado FC 26.

3. Recursos Avançados:

Adicione assinaturas de recursos para atualizações em tempo real.
Implemente ferramentas assíncronas para tarefas complexas.
Adicione autenticação para acesso seguro.

Dicas de Solução de Problemas

Servidor Não Iniciando? Verifique se o Java 24 e o Maven estão instalados e confira o pom.xml para dependências corretas.
Problemas com o MCP Inspector? Certifique-se de que o Node.js está instalado e o caminho do JAR está correto.
Cliente Não Conectando? Confirme o caminho do JAR na configuração do cliente e reinicie o cliente.
Nenhum Dado Retornado? Verifique PresentationTools para anotações de ferramenta corretas e inicialização de dados.

Por Que Usar o Servidor MCP Java?

O Servidor MCP Java é uma maneira fantástica de conectar seu aplicativo Java a modelos de IA, permitindo que eles acessem seus dados em tempo real. Nosso servidor com tema de jogos mostrou como é fácil compartilhar dados como “GTA 6” ou “FC 26” com Claude ou Cursor. O SDK Java do MCP simplifica a definição de ferramentas, e o transporte STDIO mantém as coisas leves. Seja você construindo para jogos, cursos ou qualquer outra coisa, este servidor é sua porta de entrada para a integração de IA.

Conclusão

Agora você é um profissional em Servidor MCP Java! Você construiu um servidor do zero, testou-o com dados de jogos e aprendeu como estendê-lo com novas ferramentas. O SDK Java do MCP facilita a conexão do seu aplicativo com assistentes de IA, e nosso teste mostrou que ele funciona. Tente adicionar mais dados ou ferramentas para tornar seu servidor ainda mais poderoso.

💡

button