create_appointment

Schedule patient appointments with providers by specifying patient, provider, department, appointment type, date, and time. Supports optional duration, reason, and notes for comprehensive scheduling within healthcare workflows.

Instructions

Create a new appointment for a patient

Input Schema

TableJSON Schema

Name	Required	Description
`patient_id`	Yes	Patient ID
`provider_id`	Yes	Provider ID
`department_id`	Yes	Department ID
`appointment_type`	Yes	Appointment type
`date`	Yes	Appointment date (YYYY-MM-DD)
`start_time`	Yes	Start time (HH:MM)
`duration`	No	Duration in minutes (optional)
`reason`	No	Reason for visit (optional)
`notes`	No	Appointment notes (optional)

Implementation Reference

src/handlers/tool-handlers.ts:148-191 (handler)

The primary handler function for the 'create_appointment' MCP tool. It processes input arguments, calls the AthenaHealthClient to create the appointment, logs the action, and returns the result or error in MCP format.

async handleCreateAppointment(args: any) {
  try {
    const appointment = await this.client.createAppointment({
      patientid: args.patient_id,
      providerid: args.provider_id,
      departmentid: args.department_id,
      appointmenttype: args.appointment_type,
      date: args.date,
      starttime: args.start_time,
      duration: args.duration,
      reasonforvisit: args.reason,
      appointmentnotes: args.notes,
    });

    auditLog('APPOINTMENT_CREATE', {
      patientId: args.patient_id,
      result: 'success',
      resourceType: 'APPOINTMENT',
    });

    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(appointment, null, 2),
        },
      ],
    };
  } catch (error: any) {
    console.error('Create appointment error:', error);
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify({
            error: 'Failed to create appointment',
            message: error.message || 'Unknown error occurred',
            details: error.details || error.message,
            note: 'This endpoint may not be available in the preview/sandbox environment or may require specific appointment types',
          }, null, 2),
        },
      ],
    };
  }

src/definitions/tools.ts:57-74 (schema)

The tool definition including name, description, and input schema validation for 'create_appointment'.

  name: 'create_appointment',
  description: 'Create a new appointment for a patient',
  inputSchema: {
    type: 'object',
    properties: {
      patient_id: { type: 'string', description: 'Patient ID' },
      provider_id: { type: 'string', description: 'Provider ID' },
      department_id: { type: 'string', description: 'Department ID' },
      appointment_type: { type: 'string', description: 'Appointment type' },
      date: { type: 'string', description: 'Appointment date (YYYY-MM-DD)' },
      start_time: { type: 'string', description: 'Start time (HH:MM)' },
      duration: { type: 'string', description: 'Duration in minutes (optional)' },
      reason: { type: 'string', description: 'Reason for visit (optional)' },
      notes: { type: 'string', description: 'Appointment notes (optional)' },
    },
    required: ['patient_id', 'provider_id', 'department_id', 'appointment_type', 'date', 'start_time'],
  },
},

src/mcp-server.ts:166-168 (registration)
Registration of all tool definitions (including create_appointment) via the ListToolsRequestHandler in the MCP server.
```
this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools: toolDefinitions };
});
```
src/mcp-server.ts:185-186 (registration)
Dispatch registration in the MCP server's CallToolRequestHandler switch statement that routes 'create_appointment' calls to the specific handler method.
```
case 'create_appointment':
  return await this.toolHandlers.handleCreateAppointment(args);
```

athenahealth MCP Server