> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcprank.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Servers

> Search for MCP servers matching a query

## Overview

The search endpoint performs semantic search over 490+ MCP servers to find the most relevant tools for your query. Results are ranked using a combination of semantic similarity and popularity metrics.

## Request

<ParamField body="query" type="string" required>
  The search query text. Minimum 1 character, maximum 1000 characters.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Number of results to return. Minimum 1, maximum 50.
</ParamField>

### Headers

<ParamField header="X-API-Key" type="string" required>
  Your MCP Rank API key
</ParamField>

## Response

<ResponseField name="servers" type="array">
  Array of matching servers, ranked by relevance

  <Expandable title="Server object">
    <ResponseField name="id" type="string">
      Unique server identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Server name
    </ResponseField>

    <ResponseField name="description" type="string">
      Server description
    </ResponseField>

    <ResponseField name="remote_url" type="string">
      URL for connecting to the server via MCP
    </ResponseField>

    <ResponseField name="tools" type="array">
      Array of tools provided by this server

      <Expandable title="Tool object">
        <ResponseField name="name" type="string">
          Tool name
        </ResponseField>

        <ResponseField name="description" type="string">
          Tool description
        </ResponseField>

        <ResponseField name="input_schema" type="object">
          JSON Schema for tool inputs
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="scores" type="object">
      Individual scoring components

      <Expandable title="Score components">
        <ResponseField name="semantic" type="number">
          Semantic similarity score (0-1)
        </ResponseField>

        <ResponseField name="popularity" type="number">
          Popularity score based on usage (0-1)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="final_score" type="number">
      Combined ranking score
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Information about the search request

  <Expandable title="Metadata fields">
    <ResponseField name="latency_ms" type="integer">
      Search latency in milliseconds
    </ResponseField>

    <ResponseField name="cache_hit" type="boolean">
      Whether results were served from cache
    </ResponseField>

    <ResponseField name="total_candidates" type="integer">
      Total number of servers considered
    </ResponseField>

    <ResponseField name="query_log_id" type="string">
      Unique ID for this query (useful for feedback)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.mcprank.com/v1/search \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "send emails and manage calendar",
      "limit": 5
    }'
  ```

  ```python Python theme={null}
  from mcp_rank import MCPRank

  client = MCPRank(api_key="your-api-key")
  results = await client.search("send emails and manage calendar", limit=5)

  for server in results["servers"]:
      print(f"{server['name']}: {server['description']}")
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.mcprank.com/v1/search", {
    method: "POST",
    headers: {
      "X-API-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "send emails and manage calendar",
      limit: 5,
    }),
  });

  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "servers": [
      {
        "id": "google-workspace",
        "name": "Google Workspace",
        "description": "Access Gmail, Calendar, Drive, and other Google services",
        "remote_url": "https://mcp.google.com/workspace",
        "tools": [
          {
            "name": "send_email",
            "description": "Send an email via Gmail",
            "input_schema": {
              "type": "object",
              "properties": {
                "to": { "type": "string" },
                "subject": { "type": "string" },
                "body": { "type": "string" }
              },
              "required": ["to", "subject", "body"]
            }
          },
          {
            "name": "create_calendar_event",
            "description": "Create a new calendar event",
            "input_schema": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "start_time": { "type": "string" },
                "end_time": { "type": "string" }
              },
              "required": ["title", "start_time"]
            }
          }
        ],
        "scores": {
          "semantic": 0.92,
          "popularity": 0.85
        },
        "final_score": 0.89
      }
    ],
    "metadata": {
      "latency_ms": 45,
      "cache_hit": false,
      "total_candidates": 492,
      "query_log_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
  ```
</ResponseExample>

## Error Responses

| Status Code | Description                            |
| ----------- | -------------------------------------- |
| 400         | Invalid request (e.g., query too long) |
| 401         | Missing or invalid API key             |
| 429         | Rate limit exceeded                    |
| 500         | Internal server error                  |