MCP server
The AlignAI MCP (Model Context Protocol) server lets any MCP-compatible AI client — Cursor, Claude Code, VS Code/GitHub Copilot, Claude Desktop, Windsurf, or ChatGPT — read and write your AlignAI governance data conversationally, without you writing REST calls by hand.
- Endpoint:
/api/llm/mcp - Authentication: Bearer token, required on every request (same token model as Authentication & API keys)
Getting a token
Log in
Log into your AlignAI environment.
Open Admin → Generate Token
Go to Admin → Generate Token.
Name the token and generate it
Name the token, set an expiration, and click Generate Token.
Copy and store the token
Copy and store the token immediately — it won’t be shown again.
Never commit a token to source control. Store it in an environment variable or your platform’s secret manager, and remember that a token is bound to the environment that issued it — see Authentication & API keys.
Client setup
In every config below, <server domain> and <Saved token from admin> are placeholders — substitute your environment’s host and the token you generated above.
Cursor
-
Open Cursor menu → Settings → Cursor Settings → Tools & MCP.
-
Click + New MCP Server (opens
mcp.json). -
Add:
mcp.json
{
"mcpServers": {
"alignai-mcp": {
"url": "https://<server domain>/api/llm/mcp",
"headers": {
"Authorization": "Bearer <Saved token from admin>"
}
}
}
}- Save
mcp.jsonand confirm the connection is running on the Tools & MCP page — you should see a green dot and a summary of available tools.
Tool reference
Use cases
| Tool | Parameters | Notes |
|---|---|---|
| Search Use Cases | query (required), status, limit (1–50, default 20), offset | Matches name, ID, or field content. e.g. “Search for use cases related to fraud detection.” |
| Get a Use Case | id (required, numeric) | Returns one use case with all custom field values. |
| Filter Use Cases | filters[], sortKey, sortDirection, limit (1–100, default 20), page (0-indexed) | Advanced filtering by specific field values. Ask for field definitions first so you know valid keys/values. Each filter needs key, value, and type (dropdown, dropdown-multiselect, input, textarea, searchable-text, scoring-rubric). |
| Update a Use Case | id (required), customFields (required) | Fields you don’t include are left unchanged — merge semantics, same as the REST PATCH. |
Solutions
| Tool | Parameters | Notes |
|---|---|---|
| List Solutions | limit (1–100, default 20), page (0-indexed) | Browse all solutions with linked use case IDs. |
| Get a Solution | id (required, numeric) | Returns one solution with linked use cases, documentation pages, and metadata. |
Playbooks
| Tool | Parameters | Notes |
|---|---|---|
| Search Playbooks | query, scope (all/playbooks/pages, default all), includePageContent (default false), playbookId, labelId, ownerId, capabilityId, limitPlaybooks (1–50, default 10), limitPages (1–50, default 10) | Unified search across playbooks and pages, by content, owner, or label. |
| Get a Playbook | id (required, UUID), includeContent (default false) | Returns a playbook with its pages and labels; optionally full page text. |
Resources (data sources)
| Tool | Parameters | Notes |
|---|---|---|
| List Resources | query, sortBy (default created_at), limit (1–100, default 20), page (1-indexed) | Browse or search external resources registered in the platform. Each includes name, description, type, risk level, sensitive-data flag, owner, and external URL. |
Comments
| Tool | Parameters | Notes |
|---|---|---|
| List Comments | entityType (use-case/solution), entityId, fieldKey, limit (1–100, default 20), offset | View comments on a specific field of a use case or solution. |
| Add a Comment | entityType, entityId, fieldKey, text (all required) | Post a new comment on a specific field. |
Audit history
| Tool | Parameters | Notes |
|---|---|---|
| Get Use Case History | useCaseId (required), limit (1–100, default 50) | Full change history — field changed, change type, old/new value, timestamp. |
Reference data (read-only)
| Tool | Provides |
|---|---|
| Field Definitions | All custom field definitions for use cases and solutions — keys, types, labels, and dropdown options with their values. Use this before filtering or updating so you know exactly what keys and values are valid. |
| Labels | All labels that can be applied to playbooks and pages (ID + name). |
| AI Prompt Templates | The AI prompt template configurations used by the platform (ID, name, description). |
AI prompt templates (pre-built analysis)
| Tool | Argument | What you get |
|---|---|---|
| Use Case Summary | useCaseId (string) | A structured summary: current status, key custom field values, notable recent changes. |
| Solution Analysis | solutionId (string) | Coverage analysis: how well the solution addresses its linked use cases, documentation completeness, checklist status. |
Example workflows
- Explore your governance inventory: “List all approved use cases” → “Show me the details for use case 15” → “What’s the change history?”
- Review a solution’s completeness: “Analyze solution 5” → “Get the full details” → “Show me the linked use cases”
- Find and update use cases: “Search for use cases mentioning PII” → “Filter those by high risk level” → “Update use case 42’s status to approved”
- Research playbook content: “Search playbooks for data governance” → “Get that playbook with full page content” → “What labels are applied?”
- Audit and comment: “Show the history for use case 15” → “List comments on the risk_level field” → “Add a comment noting the review is complete”
Last updated on