---
title: tld mcp
description: Run a Model Context Protocol server that exposes tld tools to AI
  agents like Claude, Gemini, and others.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

```bash
tld mcp
```

`tld mcp` starts an MCP server on stdio. Any MCP-compatible agent can connect and use these tools:

:::note
The agent skill+CLI generally works better than the MCP server for most tasks.
:::

| Tool | What the agent can do |
|---|---|
| `tld_add` | Create or update an element |
| `tld_connect` | Create a connector between elements |
| `tld_remove_element` | Remove an element |
| `tld_remove_connector` | Remove a connector |
| `tld_rename` | Rename an element |
| `tld_update_element` | Change an element's field |
| `tld_update_connector` | Change a connector's field |
| `tld_validate` | Validate the workspace |
| `tld_pull` | Fetch latest from the cloud version |
| `tld_plan` | Preview what would change |
| `tld_apply` | Push changes to the cloud version |

That's the full CRUD surface plus validation and cloud sync.

## Setting it up

Configure your AI agent's MCP settings to include the tld server:

```json
{
  "mcpServers": {
    "tld": {
      "command": "tld",
      "args": ["mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

That's it. The agent now has architecture tools.

## How it works

When `tld mcp` starts:

1. It checks if a `tld serve` instance is already running
2. If not, it launches one in the background automatically
3. It registers all CRUD and sync tools
4. It starts listening on stdio for MCP requests
5. Your agent sends tool calls , the server executes them and returns results

The MCP server uses your **current workspace** , the `.tld/` directory in the working directory (or whatever you specified with `-w`).

## Example: asking your agent to build a diagram

```
You: Create a diagram of this project's backend services

Agent: [calls tld_add with api-gateway]
Agent: [calls tld_add with auth-svc]
Agent: [calls tld_add with user-db]
Agent: [calls tld_connect between them]
Agent: [calls tld_validate to check]
Agent: [calls tld_plan to preview]

Agent: I've created a diagram with 5 elements and 4 connectors.
       Here's what `tld plan` shows...
```

## Subcommands via MCP

The MCP tools for `pull`, `plan`, and `apply` are thin wrappers that run the actual CLI subcommands. They support the same flags:

```json
// Agent calls tld_apply with { "force": true, "verbose": true }
// Equivalent to: tld apply --force --verbose
```

## Server flags

```bash
# Custom host/port for the underlying serve process
tld mcp --port 9090

# Custom data directory
tld mcp --data-dir /custom/path
```

These flags control the background `tld serve` process that gets auto-started. Most of the time you don't need them.