This guide provides step-by-step instructions for integrating the Altinity MCP Server with various AI tools and platforms.

• Install Helm Chart with Minikube and Helm from GHCR.io (Token Enabled)
• Generate Token from JWE Token Generator
• Integrate with Claude.ai Chat Web Interface
• Integrate with OpenAI ChatGPT GPTs
• Integrate with Claude Desktop
• Integrate with Claude Code
• Integrate with Cursor.com
• Integrate with Windsurf

To install the Altinity MCP Helm chart with token authentication enabled using Minikube:

1. First, ensure you have Minikube and Helm installed:

   minikube start
   helm version

2. Install the Altinity MCP Helm chart from GHCR.io with token authentication enabled:

   helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
     --set config.server.jwe.enabled=true \
     --set config.server.jwe.jweSecretKey="your-jwe-secret-key" \
     --set config.server.jwe.jwtSecretKey="your-jwt-secret-key" \
     --set config.server.transport=http \
     --set config.server.port=8080

3. Forward the port to access the service:

   kubectl port-forward service/altinity-mcp 8080:8080

For detailed configuration options, see the Helm Chart README.

To generate a JWE token for ClickHouse authentication with 24h expiry using Docker:

docker run --rm ghcr.io/altinity/altinity-mcp:latest jwe-token-generator \
  --jwe-secret-key "your-jwe-secret-key" \
  --jwt-secret-key "your-jwt-secret-key" \
  --host "clickhouse.example.com" \
  --port 8123 \
  --database "analytics" \
  --username "user123" \
  --password "password123" \
  --expiry 86400

This will output a JWE token that can be used for authentication with the Altinity MCP server.

To integrate Altinity MCP with Claude.ai:

• Navigate to https://claude.ai and log in to your account.
• Go to Settings > Connectors.

• In the Connectors settings, click on Add custom connector.

• Enter a name for your connector (e.g., altinity-mcp-jwe) and the server URL, which should include the JWE token. For example: https://host/token/http.

• After adding the connector, you can enable it for your chat session by clicking the tool icon.

• You can see the list of available tools and enable or disable them.

• Once enabled, you can use the tools in your chat. For example, you can ask Claude to list tables from your ClickHouse database.

• Claude will show the results from the tool execution.

• You can continue the conversation with Claude to analyze the data.

To integrate Altinity MCP with OpenAI GPTs:

• Navigate to https://chatgpt.com and log in to your account.
• Go to the GPTs section and click Create.

• In the configuration interface, go to the Configure tab.

• Scroll down to the Actions section and click Create new action.

• Import the OpenAPI schema from your Altinity MCP server URL. For example: https://host/openapi.

• Configure the authentication with your JWE token using the API Key option.

• Test the connection in the preview mode to ensure it's working properly.

• You can now interact with your ClickHouse database using the GPT.

To integrate Altinity MCP with Claude Desktop:

• Download and Open the Claude Desktop application https://claude.ai/download.
• Go to Settings > Developer.

• In the Local MCP servers section, click on Edit Config.
• Add your Altinity MCP server details to the configuration file.

• Save the configuration with following format:

{
  "mcpServers": {
   "altinity-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http{s}://your-mcp-host:port/generated_jwe_token/http"]
    }
  }
}

Download and install Claude Code https://www.anthropic.com/claude-code

To integrate Altinity MCP with Claude Code, you can use the claude mcp add command for HTTP transport:

claude mcp add --transport http altinity-mcp https://your-mcp-host:port/generated_jwe_token/http

Replace https://your-mcp-host:port/generated_jwe_token/http with the actual URL of your Altinity MCP server, including the JWE token and /http suffix.

This command will configure Claude Code to use your Altinity MCP server as a tool provider.

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder.

{
  "mcpServers": {
    "altinity-mcp": {
      "url": "https://your-mcp-server-url:port/default/http",
      "headers": {
        "Authorization": "Bearer your-jwe-token"
      }
    }
  }
}

See Cursor MCP docs for more info.

To integrate Altinity MCP with Windsurf, you need to add a new entry to the mcpServers section in the IDE's settings. This will allow you to use the Altinity MCP server as a tool provider. Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

{
  "mcpServers": {
    "context7": {
      "serverUrl": "https://your-mcp-server-url:port/default/http",
      "headers": {
        "Authorization": "Bearer your-jwe-token"
      }
    }
  }
}

If you encounter issues during integration:

1. Verify your Altinity MCP server is running and accessible
2. Ensure your JWE token is valid and not (use curl -vvv https://your-mcp-host/your_jwe_token/http)
3. Check that the server configuration matches the integration settings
4. Confirm network connectivity between the AI tool and your Altinity MCP server
5. Review server logs for authentication or connection errors

For more detailed troubleshooting, refer to the main README.md file.