Clinical Trials MCP Server

Instructions

Implementation Reference

• src/index.ts:2207-2307 (handler)

  The implementation of the `handleSearchInternationalStudies` tool handler, which queries the ClinicalTrials.gov API and filters results for international (multi-country) studies.

  private async handleSearchInternationalStudies(args: any) {
    const params: any = {
      format: "json",
      pageSize: args?.pageSize || 10,
    };
  
    if (args?.condition) {
      params["query.cond"] = args.condition;
    }
  
    if (args?.phase) {
      params["filter.phase"] = args.phase;
    }
  
    if (args?.includeCountry) {
      params["query.locn"] = args.includeCountry;
    }
  
    try {
      const response: AxiosResponse<StudySearchResponse> =
        await this.axiosInstance.get("/studies", { params });
  
      const studies = response.data.studies || [];
  
      // Filter for international studies
      let filteredStudies = studies.filter((study) => {
        const locations =
          study.protocolSection.contactsLocationsModule?.locations || [];
        const countries = new Set(locations.map((loc) => loc.country));
  
        // Check minimum countries requirement
        if (args?.minCountries && countries.size < args.minCountries) {
          return false;
        }
  
        // Check country exclusion
        if (args?.excludeCountry && countries.has(args.excludeCountry)) {
          return false;
        }
  
        // Only include studies with multiple countries (international)
        return countries.size >= 2;
      });
  
      const results = filteredStudies.map((study) => {
        const locations =
          study.protocolSection.contactsLocationsModule?.locations || [];
        const countries = [...new Set(locations.map((loc) => loc.country))];
  
        return {
          ...this.formatStudySummary(study),
          internationalDetails: {
            totalCountries: countries.length,
            countries: countries,
            totalLocations: locations.length,
            sampleLocations: locations.slice(0, 3),
          },
        };
      });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                searchCriteria: {
                  condition: args?.condition,
                  excludeCountry: args?.excludeCountry,
                  includeCountry: args?.includeCountry,
                  minCountries: args?.minCountries,
                  phase: args?.phase,
                  note: "Only showing studies with 2+ countries",
                },
                totalCount: response.data.totalCount || 0,
                resultsShown: results.length,
                internationalStudies: results,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [
            {
              type: "text",
              text: `Clinical Trials API error: ${
                error.response?.data?.message || error.message
              }`,
            },
          ],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:674-712 (schema)

  The tool definition and schema registration for `search_international_studies` within the `ListToolsRequestSchema` handler.

    name: "search_international_studies",
    description: "Find multi-country international clinical trials",
    inputSchema: {
      type: "object",
      properties: {
        condition: {
          type: "string",
          description: "Medical condition to filter by",
        },
        excludeCountry: {
          type: "string",
          description:
            'Country to exclude from results (e.g., "United States")',
        },
        includeCountry: {
          type: "string",
          description: "Country that must be included in results",
        },
        minCountries: {
          type: "number",
          description: "Minimum number of countries involved",
          minimum: 2,
          maximum: 50,
        },
        phase: {
          type: "string",
          description: "Study phase filter",
          enum: ["PHASE1", "PHASE2", "PHASE3", "PHASE4", "NA"],
        },
        pageSize: {
          type: "number",
          description:
            "Number of results to return (default 10, max 100)",
          minimum: 1,
          maximum: 100,
        },
      },
    },
  },

• src/index.ts:768-771 (registration)

  The request handler registration connecting the "search_international_studies" tool call to its handler function.

  case "search_international_studies":
    return await this.handleSearchInternationalStudies(
      request.params.arguments
    );