search
Query FHIR healthcare data by resource type and search parameters to find matching clinical records in a standardized format.
Instructions
Executes a standard FHIR search interaction on a given resource type, returning a bundle or list of matching resources. Use this when you need to query for multiple resources based on one or more search-parameters. Do not use this tool for create, update, or delete operations, and be aware that large result sets may be paginated by the FHIR server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The FHIR resource type name. Must exactly match one of the resource types supported by the server | |
| searchParam | Yes | A mapping of FHIR search parameter names to their values. Only include parameters supported for the resource type, as listed by `get_capabilities`. |
Implementation Reference
- src/fhir_mcp_server/server.py:253-314 (handler)The `search` tool handler function, which takes a resource `type` and `searchParam` dictionary, and uses `fhirpy` to execute the FHIR search interaction.
async def search( type: Annotated[ str, Field( description="The FHIR resource type name. Must exactly match one of the resource types supported by the server", examples=["MedicationRequest", "Condition", "Procedure"], ), ], searchParam: Annotated[ Dict[str, str | List[str]], Field( description=( "A mapping of FHIR search parameter names to their values. " "Only include parameters supported for the resource type, as listed by `get_capabilities`." ), examples=[ '{"family": "Smith"}', '{"date": ["ge1970-01-01", "lt2000-01-01"]}', ], ), ], ) -> Annotated[ list[Dict[str, Any]] | Dict[str, Any], Field( description="A dictionary containing the full FHIR resource instance matching the search criteria." ), ]: try: logger.debug(f"Invoked with type='{type}' and searchParam={searchParam}") if not type: logger.error( "Unable to perform search operation: 'type' is a mandatory field." ) return await get_operation_outcome_required_error("type") client: AsyncFHIRClient = await get_async_fhir_client() async_resources: list[Any] = ( await client.resources(type).search(Raw(**searchParam)).fetch_raw() ) logger.debug("Async resources fetched:", async_resources) return async_resources except ValueError as ex: logger.exception( f"User does not have permission to perform FHIR '{type}' resource search operation. Caused by, ", exc_info=ex, ) return await get_operation_outcome( code="forbidden", diagnostics=f"The user does not have the rights to perform search operation.", ) except OperationOutcome as ex: logger.exception( f"FHIR server returned an OperationOutcome error while searching the resource: '{type}', Caused by,", exc_info=ex, ) return ex.resource["issue"] or await get_operation_outcome_exception() except Exception as ex: logger.exception( f"An unexpected error occurred during the FHIR search operation for resource: '{type}'. Caused by, ", exc_info=ex, ) return await get_operation_outcome_exception()