# Tilores MCP Server

The Tilores MCP server gives your AI assistant direct access to Tilores
knowledge — schema design guidance, ETM pipeline recipes, rule-config
linting, GraphQL query templates, and documentation search — without
requiring you to read any docs. The assistant can design a complete
rule-config from a field list, catch common mistakes before deployment, and
explain any part of the Tilores model on demand.

!!!
The server is **stateless and read-only**. It holds no customer data, never
writes to a Tilores instance, and requires no API key. The endpoint is
public — do not send customer data or PII in your prompts while the MCP
server is active.
!!!

---

## Connecting

The server speaks the [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) over HTTP, which is supported by all major AI coding assistants.

The endpoint is:

```
https://api.tilotech.io/mcp
```

### Claude Code (CLI)

```bash
claude mcp add --transport http tilores \
  https://api.tilotech.io/mcp
```

### Claude Desktop

Open `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "tilores": {
      "type": "http",
      "url": "https://api.tilotech.io/mcp"
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project
root:

```json
{
  "mcpServers": {
    "tilores": {
      "url": "https://api.tilotech.io/mcp"
    }
  }
}
```

### Windsurf

Open **Settings → MCP** and add a new server with transport `http` and the
URL above. Or edit `~/.codeium/windsurf/mcp_config.json` directly using the
same JSON format as Cursor.

### OpenAI Codex / ChatGPT Desktop

In the ChatGPT Desktop app open **Settings → Connectors → Add MCP Server**
and enter the URL. For the Codex CLI, add to your `mcp.json`:

```json
{
  "mcpServers": {
    "tilores": {
      "url": "https://api.tilotech.io/mcp"
    }
  }
}
```

### Any other MCP-compatible client

The server accepts plain HTTP POST requests with a JSON-RPC 2.0 body. Any
client that supports the MCP streamable-HTTP transport can connect using the
URL above with no further configuration.

### Verify the connection

From a terminal you can list the available tools directly:

```bash
curl -s -X POST https://api.tilotech.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

You should get back a JSON-RPC response listing the `tilores_*` tools.

---

## What the server can do

### Schema & config design

Design a complete Tilores rule-config from a description of your use case or
a list of source fields.

> *"I have a CSV with firstName, lastName, dob, ssn, mobile, email, homeZip.
> Design a Tilores config for insurance fraud detection."*

> *"What fields and link rules would you recommend for a KYC individual
> entity?"*

### ETM pipeline generation

Generate ready-to-paste ETM transformer DAGs for standard field types —
names, phone numbers, postcodes, dates of birth, and identifier types (NPI,
SSN, EIN, VIN, DL).

> *"Give me the ETM pipeline for a US phone number field."*

> *"What transformers do I need for a German postcode?"*

### Rule-config linting

Lint a rule-config JSON and get errors and warnings with exact locations and
fix hints — single-anchor rules that over-merge, consistency/dedup rulesets
with OR-semantics traps, misplaced `consistencyRuleSetIDs`, `mustExist`
matchers feeding search rules, and reference-integrity issues.

> *"Here is my rule-config — check it for issues before I deploy."*

### GraphQL query recipes

Generate typed GraphQL queries and variable templates for the common access
patterns.

> *"Give me the GraphQL query to search by email and return id, firstName,
> lastName."*

> *"How do I fetch an entity by ID including all records and edges?"*

### Rule simulation

Simulate whether two records would match under a given rule-config — without
your own live Tilores instance — and see which link and search rules fired.

> *"Would these two records merge under this config?"*

> *"My DOB+email rule isn't firing — can you check what's happening with
> these records?"*

### Validation

Validate records, search parameters, and domain-specific identifiers against
Tilores rules and known standards.

| What to validate | Example |
|---|---|
| A record before `submitRecords` | missing `id`, empty payload |
| Search parameters | field names, value types |
| US identifiers | NPI (Luhn), SSN, EIN, VIN (check digit), DL |

> *"Is this a valid NPI: 1234567893?"*

### Documentation search & concept explanations

Look up Tilores documentation, explain concepts, and decode error messages.

> *"What is the difference between `consistencyRuleSetIDs` and
> `scores.consistency`?"*

> *"I'm getting 'field does not exist in ETM pipeline output' — what does
> that mean?"*

---

## Notes

- **Read-only** — the server only provides guidance and generates artifacts; it never writes to a Tilores instance.
- **Stateless** — each request is independent; no session history is stored.
- **No auth required** — the endpoint is public. Keep customer data and PII out of your prompts.
- **Client compatibility** — works with any assistant that supports the MCP streamable-HTTP transport.