# Lattice MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the [Lattice](https://lattice.com) Talent API as tools — so AI assistants like Claude can read and manage your people data, goals, feedback, reviews, and more.

## Prerequisites

- **Node.js** 18+
- A **Lattice API key** (generate one from your Lattice admin dashboard under **Integrations → API**)

## Quick Start

### 1. Clone & install

```bash
git clone https://github.com/EoinFalconer/lattice-mcp.git
cd lattice-mcp
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Configure your MCP client

Add the server to your MCP client configuration. For example, in Claude Code (`~/.claude/settings.json` or project-level `.mcp.json`):

```json
{
  "mcpServers": {
    "lattice": {
      "command": "node",
      "args": ["/absolute/path/to/lattice-mcp/dist/index.js"],
      "env": {
        "LATTICE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

For EMEA data residency, add `"LATTICE_REGION": "emea"` to the `env` block.

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `LATTICE_API_KEY` | Yes | — | Your Lattice API key |
| `LATTICE_REGION` | No | `us` | Data residency region: `us` or `emea` |

## Available Tools (30)

### Users
| Tool | Description |
|---|---|
| `get_current_user` | Get the authenticated user |
| `get_user` | Get a user by ID |
| `list_users` | List all users (paginated) |
| `get_user_direct_reports` | Get a user's direct reports |
| `get_user_custom_attributes` | Get custom attributes for a user |
| `get_user_goals` | Get goals for a user |
| `get_user_tasks` | Get tasks for a user |

### Goals
| Tool | Description |
|---|---|
| `get_goal` | Get a goal by ID |
| `list_goals` | List goals, optionally filtered by state |
| `create_goal` | Create a new goal |
| `update_goal` | Update an existing goal (full PUT) |

### Goal Updates
| Tool | Description |
|---|---|
| `create_goal_update` | Add a progress update to a goal |
| `get_goal_updates` | Get updates for a specific goal |
| `list_all_goal_updates` | Get all goal updates across goals |

### Departments
| Tool | Description |
|---|---|
| `get_department` | Get a department by ID |
| `list_departments` | List all departments |

### Feedback
| Tool | Description |
|---|---|
| `get_feedback` | Get a feedback entry by ID |
| `list_feedback` | List all continuous feedback |

### Review Cycles
| Tool | Description |
|---|---|
| `get_review_cycle` | Get a review cycle by ID |
| `list_review_cycles` | List all review cycles |
| `get_review_cycle_reviewees` | Get reviewees for a cycle |
| `get_review_cycle_reviews` | Get reviews for a cycle |

### Reviewees
| Tool | Description |
|---|---|
| `get_reviewee` | Get a reviewee by ID |
| `get_reviewee_reviews` | Get reviews for a reviewee |

### Questions
| Tool | Description |
|---|---|
| `get_question` | Get a review question by ID |
| `get_question_revision` | Get a question revision by ID |

### Other
| Tool | Description |
|---|---|
| `get_competency` | Get a competency by ID |
| `get_custom_attribute` | Get a custom attribute definition |
| `get_custom_attribute_value` | Get a custom attribute value |
| `get_tag` / `list_tags` | Get or list tags |
| `get_update` / `list_updates` | Get or list updates |
| `get_task` | Get a task by ID |

## API Notes

- **Pagination** — Cursor-based. Use `limit` (1–100) and `startingAfter` (the `endingCursor` from the previous response).
- **Rate limits** — 240 requests/minute. 429 responses include a `Retry-After` header.
- **Base URLs** — US: `api.latticehq.com` / EMEA: `api.emea.latticehq.com`

## License

ISC