Apache Pinot + OpenCode: Complete MCP Integration
Apache Pinot is a MCP server that MCP server for Apache Pinot real-time analytics database with SQL query capabilities and metadata access.
When integrated with OpenCode, you can:
- List and inspect Apache Pinot tables
- View and analyze table segments
- Retrieve and analyze table schemas
This guide provides step-by-step instructions to set up Apache Pinot in OpenCode, including configuration, examples, and troubleshooting.
What You'll Achieve
After completing this setup:
- Apache Pinot will be fully integrated and operational
- You can use Apache Pinot tools directly in OpenCode
- All Apache Pinot capabilities will be available for your workflows
- Access to 5 different tools
Prerequisites
Before starting, ensure you have:
- Apache Pinot broker hostname
- Apache Pinot broker port
- OpenCode installed and configured
- Compatible operating system (macOS, Linux, Windows)
Installation
Step 1: Install Apache Pinot
Configuration
Step 2: Configure OpenCode
-
Locate your configuration file:
-
Add server configuration:
Configure MCP servers in your `opencode.json` or `opencode.jsonc`:
```json
{
"mcp": {
"my-mcp": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
"environment": {
"API_KEY": "$API_KEY"
},
"timeout": 5000
},
"remote-server": {
"type": "remote",
"url": "https://mcp.example.com/sse",
"headers": {
"Authorization": "Bearer $API_TOKEN"
}
}
}
}
Disable a server temporarily:
{
"mcp": {
"my-mcp": {
"type": "local",
"command": ["npx", "-y", "mcp-server"],
"enabled": false
}
}
}
3. **Restart OpenCode**
Completely quit and restart OpenCode to load the new configuration.
## Examples
Once configured, you can use Apache Pinot in OpenCode:
### List All Tables
Get overview of available Pinot tables
**Ask OpenCode:** "Show me all the tables available in the Pinot cluster"
**Expected Result:** List of table names with basic metadata and schema information
### Execute Analytics Query
Run SQL query for real-time analytics
**Ask OpenCode:** "SELECT COUNT(*) FROM events WHERE timestamp > now() - 3600000"
**Expected Result:** Query results showing event count for last hour
### Analyze Table Structure
Get detailed schema information for a table
**Ask OpenCode:** "Show me the schema and structure of the user_events table"
**Expected Result:** Table schema with column names, types, and index information
### Generate Data Visualization
Create histogram plots from query results
**Ask OpenCode:** "Create a histogram showing user activity distribution by hour"
**Expected Result:** Histogram visualization with data aggregated by time buckets
## Testing Your Setup
1. Run opencode in terminal
2. Add "use the mcp_name tool" to your prompts
3. Verify tool execution and response
## Troubleshooting
### Common Issues
#### uv Command Not Found
**Symptoms:** Command not found error, uv: command not found
**Cause:** uv package manager not installed
**Solution:**
- Install uv using: curl -LsSf https://astral.sh/uv/install.sh | sh
- Restart terminal or source shell configuration
- Verify installation with: uv --version
#### Pinot Connection Failed
**Symptoms:** Connection refused, Broker unreachable, Network timeout
**Cause:** Invalid Pinot broker configuration or cluster not running
**Solution:**
- Verify PINOT_BROKER_HOST and PINOT_BROKER_PORT in .env file
- Check Pinot cluster is running and accessible
- Test connection: telnet <broker_host> <broker_port>
- Ensure firewall allows connections to Pinot broker
#### Environment Variables Not Loaded
**Symptoms:** Config missing errors, Default values being used
**Cause:** .env file not found or incorrectly formatted
**Solution:**
- Create .env file in repository root directory
- Copy from .env.example and modify values
- Ensure no spaces around = in variable assignments
- Restart MCP server after configuration changes
#### Claude Desktop Not Recognizing Server
**Symptoms:** Server not appearing, Connection errors in Claude
**Cause:** Incorrect claude_desktop_config.json configuration
**Solution:**
- Verify path to uv binary in command field
- Ensure correct path to mcp-pinot repository
- Restart Claude Desktop after configuration changes
- Check Claude Desktop logs for error messages
#### MCP Server Not Loading
**Symptoms:** Server not appearing in tools, Timeout errors, Command not found
**Cause:** Invalid configuration, missing dependencies, or timeout too short
**Solution:**
- Verify command array is correct in opencode.json
- Check environment variables are set properly
- Increase timeout value if server takes longer to start
- Test MCP server command independently in terminal
#### Context Limit Exceeded
**Symptoms:** Context too large errors, Slow responses, Truncated output
**Cause:** Too many MCP servers adding to context
**Solution:**
- Disable unused MCP servers with enabled: false
- Use per-agent tool configuration to limit active MCPs
- Avoid MCP servers that add many tokens (e.g., GitHub MCP)
#### Remote Server Connection Failed
**Symptoms:** Cannot connect to remote MCP, Authentication errors
**Cause:** Invalid URL, missing headers, or network issues
**Solution:**
- Verify remote server URL is correct
- Check authorization headers are properly configured
- Ensure environment variables for tokens are set
#### Apache Pinot not appearing in OpenCode
**Symptoms:** Server not listed, Tools not available
**Cause:** Configuration or installation issue
**Solution:**
- Verify configuration syntax
- Check Apache Pinot installation
- Restart OpenCode
- Check logs for error messages
## Next Steps
Now that Apache Pinot is integrated with OpenCode:
- Explore all Apache Pinot capabilities through OpenCode
- Check out other MCP servers that work with OpenCode
- Join the MCP community for tips and support
- Consider contributing to Apache Pinot development
## Need Help?
- Search for [Apache Pinot documentation](https://www.mcpstack.org)
- Check the [OpenCode MCP guide](https://www.mcpstack.org/clients)
- Join the MCP community discussions