get_patient_encounters

Retrieve patient encounter records from athenahealth to review medical visits, treatments, and clinical history for care coordination and documentation.

Instructions

Get all encounters for a patient

Input Schema

TableJSON Schema

Name	Required	Description
`patient_id`	Yes	Patient ID
`department_id`	No	Filter by department ID (optional)
`start_date`	No	Start date filter (YYYY-MM-DD) (optional)
`end_date`	No	End date filter (YYYY-MM-DD) (optional)
`status`	No	Filter by status: OPEN, CLOSED, SIGNED (optional)

Implementation Reference

src/definitions/tools.ts:167-181 (schema)

Tool schema definition with input validation schema for get_patient_encounters

{
  name: 'get_patient_encounters',
  description: 'Get all encounters for a patient',
  inputSchema: {
    type: 'object',
    properties: {
      patient_id: { type: 'string', description: 'Patient ID' },
      department_id: { type: 'string', description: 'Filter by department ID (optional)' },
      start_date: { type: 'string', description: 'Start date filter (YYYY-MM-DD) (optional)' },
      end_date: { type: 'string', description: 'End date filter (YYYY-MM-DD) (optional)' },
      status: { type: 'string', description: 'Filter by status: OPEN, CLOSED, SIGNED (optional)' },
    },
    required: ['patient_id'],
  },
},

src/mcp-server.ts:206-207 (registration)
Registration and dispatch of get_patient_encounters tool call to the handler in MCP server
```
case 'get_patient_encounters':
  return await this.toolHandlers.handleGetPatientEncounters(args);
```

src/handlers/tool-handlers.ts:470-510 (handler)

Primary handler function executing the tool: extracts parameters, calls AthenaHealthClient, audits access, returns JSON response or error

async handleGetPatientEncounters(args: any) {
  try {
    const { patient_id, department_id, start_date, end_date, status } = args;

    const encounters = await this.client.getPatientEncounters(patient_id, {
      departmentid: department_id,
      startdate: start_date,
      enddate: end_date,
      status,
    });

    auditLog('ENCOUNTER_ACCESS', {
      patientId: patient_id,
      result: 'success',
      resourceType: 'ENCOUNTER',
    });

    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(encounters, null, 2),
        },
      ],
    };
  } catch (error: any) {
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify({
            error: 'Failed to get patient encounters',
            message: error.message || 'Unknown error occurred',
            status: error.status || null,
            note: 'Encounter endpoints may not be available in the athenahealth preview/sandbox environment.',
          }, null, 2),
        },
      ],
    };
  }
}

src/services/encounter-service.ts:5-30 (helper)

Core service implementation making the HTTP GET request to Athenahealth API for patient encounters and handling response normalization

async getPatientEncounters(patientId: string, params?: {
  departmentid?: string;
  startdate?: string;
  enddate?: string;
  status?: string;
}): Promise<Encounter[]> {
  const response = await this.makeRequest<any>(
    `${this.config.practice_id}/patients/${patientId}/encounters`,
    {
      method: 'GET',
      params,
    }
  );

  // Handle different response structures
  if (response.encounters && Array.isArray(response.encounters)) {
    return response.encounters;
  }
  if (Array.isArray(response)) {
    return response;
  }
  if (response.data && Array.isArray(response.data)) {
    return response.data;
  }
  return [];
}

athenahealth MCP Server