MCP Servers

Extend the AI's capabilities with external tools using the Model Context Protocol.

Quick Start

Give the AI access to your filesystem.

Map<String, Object> server = Map.of(
    "type", "local",
    "command", "npx",
    "args", List.of("-y", "@modelcontextprotocol/server-filesystem", "/tmp"),
    "tools", List.of("*")
);

var session = client.createSession(
    new SessionConfig()
        .setMcpServers(Map.of("filesystem", server))
).get();

var result = session.sendAndWait("List files in the directory").get();
System.out.println(result.getData().getContent());

Tip: Browse the MCP Servers Directory for community servers like GitHub, SQLite, and Puppeteer.

Local Servers

Run a tool as a subprocess (stdin/stdout communication).

Map<String, Object> server = new HashMap<>();
server.put("type", "local");
server.put("command", "node");
server.put("args", List.of("./mcp-server.js"));
server.put("env", Map.of("DEBUG", "true"));
server.put("cwd", "./servers");
server.put("tools", List.of("*"));

Option	Description
`command`	Executable to run
`args`	Command-line arguments
`env`	Environment variables
`cwd`	Working directory
`tools`	`["*"]` for all, `[]` for none, or specific tool names
`timeout`	Timeout in milliseconds

Remote Servers

Connect to a cloud-hosted MCP server via HTTP.

Map<String, Object> server = Map.of(
    "type", "http",
    "url", "https://api.githubcopilot.com/mcp/",
    "headers", Map.of("Authorization", "Bearer " + token),
    "tools", List.of("*")
);

Option	Description
`type`	`"http"` or `"sse"`
`url`	Server endpoint
`headers`	HTTP headers for authentication
`tools`	Tools to enable
`timeout`	Timeout in milliseconds

Multiple Servers

Combine tools from several sources.

var session = client.createSession(
    new SessionConfig()
        .setMcpServers(Map.of(
            "filesystem", filesystemServer,
            "github", githubServer,
            "database", sqliteServer
        ))
).get();

Troubleshooting

Problem	Solution
Tools not invoked	Set `tools` to `["*"]` or list specific tool names
Server not found	Verify `command` path is correct and executable
Connection refused	Check URL and authentication headers
Timeout errors	Increase `timeout` or check server performance

Debug tips:

Test your MCP server independently before integrating
Enable verbose logging in the server
Start with a simple tool to verify the integration