# MCP server

> The Layerz MCP server gives AI agents the full model, read and write, through tools and reference resources, signed in with OAuth or an API key.

The Model Context Protocol server is how an AI agent works a Layerz model. It exposes 29 tools and 5 resources at:

```
https://layerz.cc/mcp
```

## Connecting

- **OAuth** (recommended): the client registers itself, the user signs in to Layerz and approves the access. Every client listed in [Quickstart with an AI agent](/docs/get-started/quickstart-mcp) works this way.
- **API key**: a client that cannot do OAuth sends `Authorization: Bearer lz_...`. A key can be limited to one model and to read-only; the server then hides the tools the key cannot use.

## What an agent can do

| Tool | What it does |
|---|---|
| [`layerz_build_from_blueprint`](/docs/mcp/tools#layerz_build_from_blueprint) | Build from blueprint |
| [`layerz_create_model`](/docs/mcp/tools#layerz_create_model) | Create model |
| [`layerz_create_upload_url`](/docs/mcp/tools#layerz_create_upload_url) | Create file upload URL |
| [`layerz_delete_branch`](/docs/mcp/tools#layerz_delete_branch) | Delete branch |
| [`layerz_dependencies`](/docs/mcp/tools#layerz_dependencies) | Trace dependencies |
| [`layerz_diff`](/docs/mcp/tools#layerz_diff) | Diff two versions |
| [`layerz_export`](/docs/mcp/tools#layerz_export) | Export to file |
| [`layerz_external_ref`](/docs/mcp/tools#layerz_external_ref) | Link, refresh or unlink external reference |
| [`layerz_get_conventions`](/docs/mcp/tools#layerz_get_conventions) | Get conventions |
| [`layerz_get_model`](/docs/mcp/tools#layerz_get_model) | Get model detail |
| [`layerz_history`](/docs/mcp/tools#layerz_history) | List version history |
| [`layerz_import_branch`](/docs/mcp/tools#layerz_import_branch) | Import data into branch |
| [`layerz_list_integrations`](/docs/mcp/tools#layerz_list_integrations) | List data sources |
| [`layerz_list_mappings`](/docs/mcp/tools#layerz_list_mappings) | List mapping rules |
| [`layerz_list_models`](/docs/mcp/tools#layerz_list_models) | List models |
| [`layerz_list_templates`](/docs/mcp/tools#layerz_list_templates) | List templates |
| [`layerz_list_transactions`](/docs/mcp/tools#layerz_list_transactions) | List staged transactions |
| [`layerz_manage_integration`](/docs/mcp/tools#layerz_manage_integration) | Sync, configure or delete data source |
| [`layerz_manage_mapping`](/docs/mcp/tools#layerz_manage_mapping) | Set, delete or import mapping rules |
| [`layerz_manage_version`](/docs/mcp/tools#layerz_manage_version) | Pin, unpin or restore version |
| [`layerz_match_items`](/docs/mcp/tools#layerz_match_items) | Match labels to items |
| [`layerz_parse_file`](/docs/mcp/tools#layerz_parse_file) | Parse uploaded file |
| [`layerz_patch`](/docs/mcp/tools#layerz_patch) | Apply model patch |
| [`layerz_read`](/docs/mcp/tools#layerz_read) | Read model snapshot |
| [`layerz_set_custom_instructions`](/docs/mcp/tools#layerz_set_custom_instructions) | Set custom instructions |
| [`layerz_set_finance_md`](/docs/mcp/tools#layerz_set_finance_md) | Set FINANCE.md |
| [`layerz_share_model`](/docs/mcp/tools#layerz_share_model) | Invite or revoke model access |
| [`layerz_update_branch`](/docs/mcp/tools#layerz_update_branch) | Create or update branch |
| [`layerz_validate_model`](/docs/mcp/tools#layerz_validate_model) | Validate model |

## Resources

| Resource                        | Content                                                                                                                                              |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `modeling-guide://reference`    | The modeling guide: the session workflow, structure and modelling patterns, validated patch examples. Also on [this site](/docs/mcp/modeling-guide). |
| `formula-spec://reference`      | The [formula language](/docs/reference/formulas).                                                                                                    |
| `format-spec://reference`       | The [number formats](/docs/reference/number-formats).                                                                                                |
| `finance-md://model/{model_id}` | A model's FINANCE.md.                                                                                                                                |
| `custom-instructions://user`    | The conventions of the personal workspace.                                                                                                           |

## Conventions come first

Every model opened through the server comes back with `conventions`: the workspace conventions and the model's FINANCE.md. They say how to read the numbers (currency, units, signs) and how this team models. Agents read them before their first write; see [Session workflow](/docs/mcp/session-workflow).

## Safety

- Tools carry standard annotations (read-only, destructive, idempotent), so a client can ask for confirmation before a destructive call.
- Every write records a [version](/docs/concepts/versions) labelled with the agent's summary; any change can be compared and restored.
- Connector credentials never transit through MCP.
