Skip to main content

MCP Integration (Model Context Protocol)

Extend QRY's capabilities by connecting to external tools and services through the industry-standard Model Context Protocol (MCP).

What is MCP?​

Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with external data sources and tools. Think of it as a universal adapter that lets QRY communicate with any MCP-compatible service.

Why MCP Matters​

  • Extensibility: Add new capabilities without modifying QRY's code
  • Interoperability: Use the same MCP server across different AI applications
  • Security: Controlled access with authentication and permissions
  • Community: Leverage the growing ecosystem of MCP-compatible tools

Key Capabilities​

Dynamic Tool Discovery​

When you connect an MCP server, QRY automatically:

  1. Discovers all available tools from the server
  2. Integrates them into the AI's toolset
  3. Makes them available in conversations
  4. Routes tool calls to the appropriate server

Seamless Integration​

MCP tools work alongside QRY's native capabilities:

  • Transparent to Users: Users don't need to know which tools are from MCP
  • Unified Experience: Same interface for all tools
  • Automatic Routing: AI selects the right tool for the task
  • Error Handling: Graceful fallback if servers are unavailable

Secure by Default​

  • Authentication: Bearer tokens, API keys, or basic auth
  • Encryption: All communications encrypted
  • Permission Control: Admin-only configuration
  • Audit Logging: Track all MCP tool usage

Use Cases​

Analytics & BI Tools​

Example: Connect Looker or Tableau

MCP Server: business-intelligence
Tools: create_dashboard, run_report, schedule_export
Result: "Create a sales dashboard in Looker" works natively in QRY

External APIs​

Example: Weather, Stock Market, Geographic Data

MCP Server: market-data
Tools: get_stock_price, get_market_news, calculate_indicators
Result: Enrich data analysis with real-time market information

Specialized Analytics​

Example: Statistical Analysis, ML Tools

MCP Server: scipy-server
Tools: statistical_tests, curve_fitting, optimization
Result: Advanced statistical analysis beyond SQL

Internal Tools​

Example: Company-Specific Services

MCP Server: company-tools
Tools: check_inventory, process_order, send_notification
Result: Bridge data analysis with operational systems

Setup & Configuration​

Prerequisites​

  • Administrator access to QRY
  • MCP server endpoint URL
  • Authentication credentials (if required)

Adding an MCP Server​

Step 1: Navigate to Admin Panel

Admin → Integrations → MCP Servers → Add Server

Step 2: Configure Server Details

Name: analytics-tools
Display Name: Analytics Tools Server
Description: Custom analytics and reporting tools
Endpoint: https://mcp-server.company.com/mcp
Transport: HTTP
Timeout: 30 seconds

Step 3: Set Authentication

Auth Type: Bearer Token
Token: your-secure-token-here

Step 4: Advanced Settings (Optional)

Tool Whitelist: tool1, tool2, tool3 (leave empty for all)
Tool Blacklist: restricted_tool
Sandbox Mode: Enabled
Max Concurrent Connections: 5

Step 5: Test & Enable

1. Click "Test Connection"
2. Verify tools are discovered
3. Enable server
4. Tools available immediately

Configuration via API​

POST /admin/mcp-servers/
Content-Type: application/json

{
  "name": "analytics-server",
  "display_name": "Analytics MCP Server",
  "description": "Statistical analysis tools",
  "endpoint": "https://mcp.example.com",
  "transport_type": "http",
  "timeout": 30,
  "auth_type": "bearer",
  "auth_config": {
    "token": "your-secure-token"
  },
  "is_enabled": true,
  "tool_whitelist": ["analyze", "report"],
  "sandbox_enabled": true
}

MCP Server Types​

HTTP Transport​

Most common for web-based services:

Endpoint: https://mcp-server.example.com/mcp
Protocol: HTTPS
Use Case: Cloud services, APIs, external tools

Standard I/O Transport​

For local or process-based servers:

Command: /path/to/mcp-server
Protocol: stdin/stdout
Use Case: Local tools, custom scripts, containerized services

Security & Permissions​

Authentication Methods​

Bearer Token

{
  "auth_type": "bearer",
  "auth_config": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

API Key

{
  "auth_type": "api_key",
  "auth_config": {
    "api_key": "your-api-key",
    "header_name": "X-API-Key"
  }
}

Basic Authentication

{
  "auth_type": "basic",
  "auth_config": {
    "username": "admin",
    "password": "secure-password"
  }
}

No Authentication

{
  "auth_type": "none"
}

Tool Filtering​

Whitelist Approach (only specified tools allowed)

tool_whitelist: ["safe_tool1", "safe_tool2"]
Result: Only these tools available to users

Blacklist Approach (all except specified tools)

tool_blacklist: ["dangerous_tool", "restricted_tool"]
Result: All tools available except these

Sandbox Mode​

Enable sandbox mode for enhanced security:

  • Resource limits enforced
  • Network access restricted
  • File system access controlled
  • Execution timeouts

Monitoring & Management​

Health Monitoring​

Real-time server status:

Status: Connected
Uptime: 99.8%
Tools Discovered: 15
Last Health Check: 2 minutes ago
Response Time: 45ms

Usage Analytics​

Track MCP tool usage:

Total Executions: 1,247
Success Rate: 98.5%
Average Response Time: 120ms
Most Used Tool: generate_report
Failed Executions: 19

Audit Logging​

Complete audit trail:

Timestamp: 2025-10-18 14:35:22
User: alice@company.com
Server: analytics-server
Tool: generate_report
Parameters: {"date_range": "last_month"}
Result: Success
Duration: 1.2s

Building MCP Servers​

Server Requirements​

To create a compatible MCP server:

  1. Implement MCP Protocol: Follow the official MCP specification
  2. Expose Tools: Define available functions and their schemas
  3. Handle Requests: Process tool execution requests
  4. Return Results: Provide structured responses

Example: Python MCP Server​

from mcp.server import Server, Tool

class MyMCPServer(Server):
    def get_tools(self):
        return [
            Tool(
                name="analyze_data",
                description="Perform statistical analysis",
                parameters={
                    "data": {"type": "array", "description": "Data points"},
                    "method": {"type": "string", "description": "Analysis method"}
                }
            )
        ]

    async def execute_tool(self, tool_name, parameters):
        if tool_name == "analyze_data":
            result = self.perform_analysis(
                parameters["data"],
                parameters["method"]
            )
            return {"result": result}

# Start server
server = MyMCPServer()
server.run(host="0.0.0.0", port=8080)

Testing Your Server​

Use QRY's test endpoint:

POST /admin/mcp-servers/{server_id}/test

Response:
{
  "status": "success",
  "connection_time": 0.05,
  "tools_discovered": 5,
  "tools": [
    {"name": "analyze_data", "description": "..."},
    ...
  ]
}

Best Practices​

Server Configuration​

DO:

  • Use descriptive names and descriptions
  • Set appropriate timeouts (30-60s)
  • Enable health checks
  • Use whitelist for production servers
  • Enable sandbox mode for untrusted servers

DON'T:

  • Store credentials in version control
  • Allow unrestricted network access
  • Skip connection testing
  • Use overly permissive settings

Performance Optimization​

  • Connection Pooling: Reuse connections to servers
  • Caching: Cache tool discovery responses
  • Timeouts: Set realistic timeouts for tool execution
  • Monitoring: Track response times and failures

Error Handling​

MCP integration gracefully handles failures:

  • Server unavailable → Tool not available
  • Timeout → Clear error message to user
  • Authentication failure → Admin notification
  • Tool execution error → Detailed error log

Troubleshooting​

Server Won't Connect​

Check:

  1. Endpoint URL is correct and accessible
  2. Authentication credentials are valid
  3. Firewall allows outbound connections
  4. Server is running and healthy

Test:

curl -X GET https://your-mcp-server.com/health

Tools Not Appearing​

Check:

  1. Server is enabled in configuration
  2. Tool whitelist/blacklist settings
  3. Server successfully completed tool discovery
  4. Worker has been restarted after configuration

Verify:

GET /admin/mcp-servers/{server_id}/tools

Tool Execution Failures​

Check:

  1. Tool parameters are correct
  2. Server logs for specific errors
  3. Timeout settings are sufficient
  4. User has required permissions

Debug:

GET /admin/mcp-servers/{server_id}/usage-logs?limit=50

FAQ​

Q: Can I use multiple MCP servers simultaneously? A: Yes, QRY can connect to multiple MCP servers and aggregate their tools.

Q: What happens if an MCP server goes offline? A: Tools from that server become unavailable, but QRY continues working with other tools.

Q: Can I restrict which users can access MCP tools? A: Yes, through QRY's permission system and tool filtering configuration.

Q: Are MCP tools free to use? A: It depends on the MCP server provider. Check with the specific service for pricing.

Q: Can I build my own MCP server? A: Yes! Follow the MCP specification and integrate your custom tools.

Q: How do I update an MCP server configuration? A: Use the admin panel or API to modify settings. Changes take effect immediately.

Resources​

  • MCP Specification: Official MCP Protocol
  • Server Examples: Community MCP server implementations
  • Support: Contact your administrator for MCP setup assistance

MCP integration makes QRY infinitely extensible - connect to any service, add any capability, and create a truly unified analytics platform.

QRYA product of IXEN.