athenahealth MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/handlers/tool-handlers.ts:399-468 (handler)

  MCP tool handler function that processes arguments, constructs patient data, calls the client to create patient, logs audit, and returns JSON response or error.
  async handleCreatePatient(args: any) { try { console.error('handleCreatePatient received args:', JSON.stringify(args, null, 2)); const patientData = { firstname: args.firstname, lastname: args.lastname, dob: args.dob, sex: args.sex, departmentid: args.department_id, email: args.email, mobilephone: args.mobile_phone, homephone: args.home_phone, address1: args.address1, city: args.city, state: args.state, zip: args.zip, guarantorfirstname: args.guarantor_firstname, guarantorlastname: args.guarantor_lastname, guarantordob: args.guarantor_dob, guarantorrelationshiptopatient: args.guarantor_relationship, }; console.error('patientData before cleanup:', JSON.stringify(patientData, null, 2)); // Remove undefined fields Object.keys(patientData).forEach(key => { if (patientData[key as keyof typeof patientData] === undefined) { delete patientData[key as keyof typeof patientData]; } }); console.error('patientData after cleanup:', JSON.stringify(patientData, null, 2)); const patient = await this.client.createPatient(patientData); auditLog('PATIENT_CREATE', { result: 'success', resourceType: 'PATIENT', }); return { content: [ { type: 'text' as const, text: JSON.stringify(patient, null, 2), }, ], }; } catch (error: any) { console.error('Create patient error:', error); return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Failed to create patient', message: error.message || 'Unknown error occurred', error_code: error.error || null, detailcode: error.detailcode || null, api_details: error.details || null, api_response: error.response || null, status_code: error.status || null, note: 'Check the api_response field for specific validation errors from athenahealth', }, null, 2), }, ], }; } }
• src/definitions/tools.ts:142-166 (schema)

  Tool schema definition including name, description, and detailed input schema with required and optional fields for creating a patient.
  name: 'create_patient', description: 'Register a new patient in the system', inputSchema: { type: 'object', properties: { firstname: { type: 'string', description: 'Patient first name' }, lastname: { type: 'string', description: 'Patient last name' }, dob: { type: 'string', description: 'Date of birth (MM/DD/YYYY or YYYY-MM-DD)' }, sex: { type: 'string', description: 'Sex (M or F)' }, department_id: { type: 'string', description: 'Primary department ID' }, email: { type: 'string', description: 'Email address (optional)' }, mobile_phone: { type: 'string', description: 'Mobile phone number (optional)' }, home_phone: { type: 'string', description: 'Home phone number (optional)' }, address1: { type: 'string', description: 'Street address (optional)' }, city: { type: 'string', description: 'City (optional)' }, state: { type: 'string', description: 'State (optional)' }, zip: { type: 'string', description: 'ZIP code (optional)' }, guarantor_firstname: { type: 'string', description: 'Guarantor first name (optional)' }, guarantor_lastname: { type: 'string', description: 'Guarantor last name (optional)' }, guarantor_dob: { type: 'string', description: 'Guarantor date of birth (optional)' }, guarantor_relationship: { type: 'string', description: 'Relationship to patient: 1=Self, 2=Spouse, 3=Child, 4=Other (optional)' }, }, required: ['firstname', 'lastname', 'dob', 'sex', 'department_id'], }, },
• src/mcp-server.ts:203-204 (registration)

  Registration of the create_patient tool in the MCP server's tool call handler switch statement, delegating to ToolHandlers.handleCreatePatient.
  case 'create_patient': return await this.toolHandlers.handleCreatePatient(args);
• src/services/patient-service.ts:63-110 (helper)

  Service method that implements the actual API call to athenahealth to create a patient using POST /patients with form-encoded data.
  async createPatient(patientData: { firstname: string; lastname: string; dob: string; sex: string; departmentid: string; email?: string; mobilephone?: string; homephone?: string; address1?: string; city?: string; state?: string; zip?: string; guarantorfirstname?: string; guarantorlastname?: string; guarantordob?: string; guarantorrelationshiptopatient?: string; }): Promise<any> { try { console.error('Creating patient with data:', JSON.stringify(patientData, null, 2)); const formData = new URLSearchParams(); Object.entries(patientData).forEach(([key, value]) => { if (value !== undefined && value !== null) { formData.append(key, String(value)); } }); console.error('Form data:', formData.toString()); const response = await this.makeRequest<any>( `${this.config.practice_id}/patients`, { method: 'POST', data: formData.toString(), headers: { 'Content-Type': 'application/x-www-form-urlencoded', }, } ); console.error('Create patient response:', JSON.stringify(response, null, 2)); return response; } catch (error: any) { console.error('Create patient error:', error.message); console.error('Error response:', JSON.stringify(error.response?.data, null, 2)); throw error; } }