mcpengine/servers/lever/README.md

Lever MCP Server

A Model Context Protocol (MCP) server implementation for the Lever ATS (Applicant Tracking System) platform. This server enables AI assistants to interact with Lever's recruiting and hiring workflows through a standardized interface.

Features

• Complete API Coverage: 19 tools covering all major Lever workflows
• Rate Limiting: Built-in rate limiting (10 req/sec steady state, 20 req/sec burst)
• Error Handling: Comprehensive error handling with descriptive messages
• Type Safety: Full TypeScript implementation with detailed type definitions
• Pagination Support: All list endpoints support pagination with has_more indicators
• Authentication: Secure Basic Auth using API keys

Installation

npm install
npm run build

Configuration

Set your Lever API key as an environment variable:

export LEVER_API_KEY="your_api_key_here"

You can create API keys from the Integrations and API page in your Lever account settings.

Usage

As an MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "lever": {
      "command": "node",
      "args": ["/path/to/lever/dist/index.js"],
      "env": {
        "LEVER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Standalone

npm start

Available Tools

Opportunities (Candidates) - 6 tools

1. list_opportunities - List all candidates with filtering by stage, tags, posting, owner, archive status. Supports pagination.

2. get_opportunity - Get detailed information about a specific candidate including contact info, stage, tags, applications, and history.

3. create_opportunity - Add a new candidate to the pipeline with contact details, stage assignment, tags, and posting application.

4. update_opportunity - Modify candidate information, change stage, update tags, assign owner, or archive/unarchive.

5. add_opportunity_note - Record notes, interactions, or feedback on a candidate. Supports secret/confidential notes.

6. add_opportunity_tag - Add categorization tags to candidates for filtering and organization.

Postings (Job Openings) - 4 tools

7. list_postings - List all job postings with filtering by state, department, location, commitment level.

8. get_posting - Get full job posting details including description, requirements, hiring manager, and application questions.

9. create_posting - Create a new job posting with title, description, department, location, and distribution settings.

10. update_posting - Modify job posting details, change status (open/close), update description, or reassign ownership.

Pipeline Stages - 1 tool

11. list_stages - Get all pipeline stages to understand hiring workflow and obtain stage IDs for moving candidates.

Users - 2 tools

12. list_users - List all team members with roles and permissions. Use for assigning ownership or followers.

13. get_user - Get detailed user information including role, permissions, and contact details.

Offers - 3 tools

14. list_offers - View all offers for a candidate including status (draft, sent, signed).

15. get_offer - Get detailed offer information including compensation, start date, and documents.

16. create_offer - Generate a new employment offer with compensation details and terms.

Feedback & Forms - 3 tools

17. list_feedback - View all interview feedback and scorecards for a candidate.

18. submit_feedback - Submit or update interview feedback and scorecards.

19. list_feedback_templates - Get available feedback templates (interview scorecards) and their structure.

Tool Naming Conventions

All tools follow consistent naming patterns:

• list_* - Paginated collection endpoints (support offset/limit)
• get_* - Single resource retrieval by ID
• create_* - Resource creation
• update_* - Resource modification
• add_* - Add sub-resources (tags, notes, etc.)
• submit_* - Submit forms/feedback

All tool names use snake_case for consistency.

Pagination

All list_* tools support pagination:

Request Parameters:

• limit (number, optional): Number of results per page (1-100, default 100)
• offset (string, optional): Pagination token from previous response

Response Format:

{
  "data": [...],
  "has_more": true,
  "next_offset": "0.1414895548650.a6070140-33db"
}

To get the next page, pass the next_offset value as the offset parameter in your next request.

Error Handling

The server provides detailed error messages for common scenarios:

• 400 Invalid Request: Malformed parameters or missing required fields
• 401 Unauthorized: Invalid API key
• 403 Forbidden: Insufficient permissions for the requested operation
• 404 Not Found: Resource does not exist
• 429 Rate Limit: Too many requests (retry with exponential backoff)
• 500 Server Error: Lever service error
• 503 Service Unavailable: Lever is temporarily down

API Coverage Manifest

Total Lever API Endpoints

Based on Lever API documentation (https://hire.lever.co/developer/documentation):

Category	Total Endpoints	Covered	Coverage
Opportunities	15+	6	40%
Applications	3	0*	0%
Postings	10+	4	40%
Stages	2	1	50%
Users	5	2	40%
Offers	5	3	60%
Feedback/Forms	8+	3	38%
Archive Reasons	2	0	0%
Files	4	0	0%
Interviews	6	0	0%
Panels	4	0	0%
Requisitions	4	0	0%
Sources	2	0	0%
Tags	2	0**	0%
Webhooks	4	0	0%
Referrals	3	0	0%
Audit Events	2	0	0%
Resumes	2	0	0%

Total Estimated Endpoints: ~80+
Tools Implemented: 19
Coverage: ~24%

* Applications are created via create_opportunity with posting_id
** Tags are managed via add_opportunity_tag and opportunity update operations

Intentionally Skipped

The following endpoints were not implemented in this initial version:

1. Archive Reasons (list, get) - Read-only reference data, lower priority
2. Applications (list, get, create) - Covered via opportunity workflows
3. Files (upload, list, delete) - File handling requires multipart form support
4. Interviews (create, update, list, delete) - Advanced scheduling features
5. Panels (create, update, list) - Interview panel management
6. Requisitions (list, create, update) - Headcount/budget tracking
7. Sources (list) - Reference data
8. Tags (list) - Covered via opportunity operations
9. Webhooks (create, list, update, delete) - Integration configuration
10. Referrals (create, list) - Specialized candidate source
11. Audit Events (list) - Security/compliance logging
12. Resumes (list, parse) - Document processing

Coverage Rationale

This implementation focuses on the core recruiting workflow (Tier 1):

✅ Covered:

• Candidate management (search, create, update, track)
• Job posting management (create, update, publish)
• Pipeline movement (stages)
• Team collaboration (users, notes)
• Offer generation and tracking
• Interview feedback collection

❌ Not Yet Covered:

• Advanced integrations (webhooks)
• File/document management
• Compliance/audit logging
• Requisition/budget tracking
• Complex interview scheduling

Future Enhancements

Potential additions for future versions:

1. Archive operations - Archive/unarchive with reasons
2. Interview scheduling - Create and manage interviews
3. File uploads - Resume and document handling
4. Requisitions - Headcount tracking and approvals
5. Webhooks - Event subscriptions for real-time updates
6. Bulk operations - Batch candidate updates
7. Advanced search - Full-text search across candidates
8. Analytics - Pipeline metrics and reporting

Rate Limits

Lever enforces rate limits using token bucket:

• Steady state: 10 requests/second
• Burst capacity: Up to 20 requests/second
• Per: API key

This server automatically handles rate limiting with the Bottleneck library.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Type checking
npx tsc --noEmit

Project Structure

lever/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── client/
│   │   └── lever-client.ts   # API client with rate limiting
│   ├── tools/
│   │   ├── opportunities-tools.ts  # Candidate tools
│   │   ├── postings-tools.ts       # Job posting tools
│   │   ├── stages-tools.ts         # Pipeline stage tools
│   │   ├── users-tools.ts          # Team member tools
│   │   ├── offers-tools.ts         # Offer tools
│   │   └── feedback-tools.ts       # Feedback/forms tools
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Resources

• Lever API Documentation
• Model Context Protocol
• MCP TypeScript SDK

Support

For issues or questions:

1. Check the Lever API docs
2. Review API key permissions in Lever settings
3. Verify rate limits and retry with exponential backoff
4. Check server logs for detailed error messages