MCP Hub Tools

# MCP Hub Tools - HTTP MCP Server Documentation This is the documentation and configuration repository for MCP Hub's HTTP-based MCP (Model Context Protocol) server. The server allows searching and discovering MCPs through a standardized HTTP interface. ## Overview MCP Hub implements [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/specification) HTTP endpoints within a Next.js application, providing a modern and accessible way for AI assistants and development tools to discover and interact with MCPs from [MCP Hub](https://www.aimcp.info). ## Protocol Support **⚠️ Important Change**: This server **only supports HTTP-based MCP connections**. The traditional stdio-based implementation has been deprecated in favor of the more accessible and reliable HTTP interface. ## Introduction `mcp-hub-tools` provides documentation and configuration for interacting with [MCP Hub](https://www.aimcp.info). The server offers standardized JSON-RPC 2.0 endpoints for searching MCPs and retrieving detailed information about registered Model Context Protocols. **Server Implementation Location**: The HTTP MCP server is actually implemented in MCP Hub's Next.js application at `/nextjs/app/api/open/mcp/route.ts`. ## Available Tools The HTTP MCP server provides the following tools via JSON-RPC 2.0: ### `search_mcp` * **Description:** Search for MCPs in the MCP Hub database using keywords. Returns a list of matching MCPs with basic information. * **Input Schema:** ```json { "type": "object", "properties": { "keywords": { "type": "string", "description": "Keywords to search for in MCP names, descriptions, and metadata" }, "limit": { "type": "number", "description": "Maximum number of results to return (default: 50)", "default": 50 } }, "required": ["keywords"] } ``` * **Output:** Returns search results with basic MCP information including: - `uuid`: Unique identifier for the MCP - `name`: MCP name - `brief`: Short description - `clicks`: Usage statistics - `count`: Total number of results found - `keywords`: Search terms used ### `get_mcp_detail` * **Description:** Get detailed information about a specific MCP using its UUID. * **Input Schema:** ```json { "type": "object", "properties": { "mcp_id": { "type": "string", "description": "The UUID of the MCP to retrieve details for" } }, "required": ["mcp_id"] } ``` * **Output:** Returns comprehensive MCP information including: - `id`: Internal database ID - `uuid`: Unique identifier - `name`: MCP name - `brief`: Description - `website_url`: Official website - `author_name`: Creator information - `created_at` / `updated_at`: Timestamps - `is_recommended` / `is_official`: Status flags - `clicks`: Usage statistics - `tags`: Associated categories - `metadata`: Additional information - `mcp_avatar_url` / `user_avatar_url`: Profile images ### Example Tool Responses #### `search_mcp` Response Example ```json { "success": true, "data": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "Blockchain MCP", "brief": "A Model Context Protocol for blockchain data analysis", "clicks": 142 } ], "count": 1, "total_results": 1, "keywords": "blockchain" } ``` #### `get_mcp_detail` Response Example ```json { "success": true, "data": { "id": 123, "uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "Blockchain MCP", "brief": "A comprehensive Model Context Protocol for blockchain data analysis", "website_url": "https://github.com/example/blockchain-mcp", "author_name": "Example Developer", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-03-20T14:45:00Z", "is_recommended": true, "is_official": false, "clicks": 142, "tags": ["blockchain", "crypto", "data-analysis"], "metadata": { "version": "1.2.0", "license": "MIT" }, "mcp_avatar_url": "https://example.com/avatar.png", "user_avatar_url": "https://example.com/user.png" } } ``` ## HTTP-based MCP Server MCP Hub provides a modern HTTP-based MCP server implementation within its Next.js application that offers superior reliability and accessibility compared to traditional stdio-based approaches. The server implements the Model Context Protocol using JSON-RPC 2.0 over HTTP. ### Server Endpoint **Production URL**: https://www.aimcp.info/api/open/mcp ### Supported Transports - **HTTP POST**: Standard JSON-RPC 2.0 requests - **Server-Sent Events (SSE)**: Real-time streaming connection for better client integration ### Key Features - ✅ **JSON-RPC 2.0 Compliance**: Full compatibility with MCP protocol specification - ✅ **Dual Transport Support**: HTTP POST and SSE for different client needs - ✅ **API Key Authentication**: Secure access control - ✅ **Rate Limiting**: Built-in protection against abuse - ✅ **CORS Support**: Cross-origin requests enabled - ✅ **Error Handling**: Comprehensive error responses ## Usage ### Prerequisites * An API key from MCP Hub ([https://www.aimcp.info](https://www.aimcp.info)) #### How to get an API key 1. Visit [https://www.aimcp.info](https://www.aimcp.info) 2. Sign up or log in to your account 3. Navigate to [API Keys page](https://www.aimcp.info/en/api-keys) 4. Generate a new API key for your application **Note**: API keys have a rate limit of 20 requests per hour. ### Authentication All requests to the HTTP MCP server require authentication using a Bearer token in the `Authorization` header: ```http Authorization: Bearer YOUR_API_KEY ``` ### MCP Client Configuration #### HTTP-based Configuration (Recommended) Modern MCP clients can connect directly to the HTTP server: ```json { "mcpServers": { "mcp-hub": { "url": "https://www.aimcp.info/api/open/mcp", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` #### Simplified Configuration For clients supporting simplified configuration: ```json { "mcpServers": { "mcp-hub": { "url": "https://www.aimcp.info/api/open/mcp", "apiKey": "YOUR_API_KEY" } } } ``` #### Cursor IDE Configuration For Cursor IDE, add to your MCP configuration: ```json { "mcpServers": { "mcp-hub": { "url": "https://www.aimcp.info/api/open/mcp", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ### Testing the Connection You can test the HTTP MCP server using curl: ```bash # Initialize connection curl -X POST https://www.aimcp.info/api/open/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' # List available tools curl -X POST https://www.aimcp.info/api/open/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' # Search for MCPs curl -X POST https://www.aimcp.info/api/open/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search_mcp", "arguments": {"keywords": "blockchain", "limit": 5}}}' ``` ## MCP Protocol Implementation ### Supported Methods The HTTP MCP server implements the following JSON-RPC 2.0 methods: - **`initialize`**: Establish connection and get server capabilities - **`tools/list`**: Retrieve available tools - **`tools/call`**: Execute specific tools with arguments ### Response Format All responses follow the JSON-RPC 2.0 specification: ```json { "jsonrpc": "2.0", "id": "request_id", "result": { // Response data } } ``` ### Error Handling Errors are returned in standard JSON-RPC 2.0 format: ```json { "jsonrpc": "2.0", "id": "request_id", "error": { "code": -32603, "message": "Error description" } } ``` ## Server Information ### Protocol Specification - **Protocol Version**: `2024-11-05` - **Server Name**: `mcp-hub-search` - **Version**: `1.0.0` - **Capabilities**: Tools enabled with change notifications ### Rate Limits - **API Requests**: 20 requests per hour per API key ### CORS Support The server supports cross-origin requests with the following headers: - `Access-Control-Allow-Origin: *` - `Access-Control-Allow-Methods: GET, POST, OPTIONS` - `Access-Control-Allow-Headers: Content-Type, Authorization, x-api-key` ## Troubleshooting ### Common Issues 1. **"0 tools enabled"**: Ensure your MCP client properly handles the `initialize` response and `capabilities.tools.listChanged` flag. 2. **Authentication errors**: Verify your API key is valid and included in the `Authorization` header. 3. **Connection timeouts**: Verify that the MCP Hub server at https://www.aimcp.info is accessible. 4. **CORS errors**: Ensure your client includes proper headers and handles preflight OPTIONS requests. ### Debug Mode For debugging, you can inspect the raw HTTP requests and responses using browser developer tools or command-line tools like curl. ## Migration from stdio-based Implementation **Important**: The stdio-based implementation has been deprecated. To migrate: 1. Update your MCP client configuration to use HTTP endpoints 2. Replace command-based configurations with URL-based ones 3. Update authentication from environment variables to HTTP headers 4. Test the new connection using the provided curl examples ## Server Architecture The HTTP MCP server is integrated into MCP Hub's Next.js application: - **Source Code Location**: `/nextjs/app/api/open/mcp/route.ts` - **Production Service**: https://www.aimcp.info/api/open/mcp ## Contributing This HTTP MCP server is part of the MCP Hub project. For issues or contributions, please visit the main repository. ## License MIT License ## Related Links - [MCP Hub Website](https://www.aimcp.info) - [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification) - [API Documentation](https://www.aimcp.info/docs/api)