# Synq With Saad: Data & Model Context Protocol (MCP) Guide

Canonical guide: https://synqwithsaad.com/data.md  
Interactive reference: https://synqwithsaad.com/data  
Discovery: https://synqwithsaad.com/llms.txt  
Full manifest: https://synqwithsaad.com/llms-full.txt  

---

## ⚡ Connect to Remote MCP

Remote MCP Endpoint: `https://synqwithsaad.com/mcp`  
Transport: **Streamable HTTP / SSE**. Public podcast transcripts, guest intelligence, and video deep links; no API key required.

> [!NOTE]
> This is a Model Context Protocol endpoint, not a standard webpage to crawl. Connect using an MCP-compatible agent or client. Discover tools with `tools/list` and inspect the `synq://data/catalog` resource.

### 1. Claude Code
Add the server for this project. Run `/mcp` inside Claude Code to verify:
```bash
claude mcp add --transport http synq https://synqwithsaad.com/mcp
```

### 2. Cursor
Merge into your project's `.cursor/mcp.json` or `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "synq": {
      "url": "https://synqwithsaad.com/mcp"
    }
  }
}
```

### 3. Antigravity
Merge into `.agents/mcp_config.json` or `~/.gemini/config/mcp_config.json`:
```json
{
  "mcpServers": {
    "synq": {
      "serverUrl": "https://synqwithsaad.com/mcp"
    }
  }
}
```

### 4. Codex CLI
```bash
codex mcp add synq --url https://synqwithsaad.com/mcp
```

### 5. VS Code GitHub Copilot
Merge into `.vscode/mcp.json`:
```json
{
  "servers": {
    "synq": {
      "type": "http",
      "url": "https://synqwithsaad.com/mcp"
    }
  }
}
```

### 6. Devin Desktop
Add a new HTTP tool under Settings > Integrations > Custom MCP:
- **Name**: `synq`
- **URL**: `https://synqwithsaad.com/mcp`
- **Transport**: `Streamable HTTP`

### 7. OpenCode & Grok CLI
```bash
opencode mcp add --http synq https://synqwithsaad.com/mcp
grok-cli tool connect --url https://synqwithsaad.com/mcp
```

---

## 📊 Transparent Token Accounting & Corpus Versioning

All API responses and data streams expose strict token telemetry headers:
```http
X-Estimated-Tokens: 14205
X-Token-Estimate-Heuristic: 1-token-per-4-serialized-characters
X-Corpus-Version: sws_57_15420_BAXktGuJ03g000000000000000000000000000000000000000000000
```
This enables agents to inspect payload token budgets before hydrating context windows.

---

## 🌐 Live REST Bulk Data Streams

Query endpoints directly in JSON or CSV by appending `?format=json` or `?format=csv`:

| Endpoint | Formats | Description |
|---|---|---|
| `GET /api/data/status` | JSON | Live freshness, row counts, and active `corpusVersion`. |
| `GET /api/data/episodes` | JSON, CSV | Full catalog of long-form and live broadcast episodes. |
| `GET /api/data/guests` | JSON, CSV | Directory of all guests, total appearances, and covered topics. |
| `GET /api/data/topics` | JSON, CSV | Aggregated topics and tags across episodes. |
| `GET /api/data/chapters` | JSON, CSV | Timed chapter markers extracted from episode descriptions. |
| `GET /api/data/transcripts` | JSON | Master index of all episodes and chunk counts. |
| `GET /api/data/transcript?id=<id>` | JSON, TEXT | Full transcript segments with timestamps (`startMs`, `endMs`). |

---

## 🧰 MCP Tools & Schemas

### 1. `search`
Hybrid vector + lexical search across all transcripts. When `query` is omitted or empty, runs in deterministic **filter-only mode** with pagination.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Search query or topic. When omitted, returns filtered episode list." },
    "guest": { "type": "string", "description": "Optional guest filter." },
    "topic": { "type": "string", "description": "Optional topic filter." },
    "limit": { "type": "integer", "default": 5 },
    "offset": { "type": "integer", "default": 0 },
    "contentVersion": { "type": "string", "description": "Optional SHA-256 hash for cache consistency." }
  }
}
```

### 2. `fetch`
Fetch complete video metadata, contiguous timestamped transcript passages, or guest dossier using canonical URN (e.g. `episode:BAXktGuJ03g`, `guest:danish-hameed`).

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "id": { "type": "string", "description": "Canonical URN (episode:ID, guest:SLUG) or videoId." },
    "section": { "type": "string", "enum": ["metadata", "transcript", "intel", "all"], "default": "metadata" },
    "startMs": { "type": "integer", "description": "Optional start timestamp in ms." },
    "endMs": { "type": "integer", "description": "Optional end timestamp in ms." },
    "query": { "type": "string", "description": "Optional filter within the transcript." }
  },
  "required": ["id"]
}
```

### 3. Transactional Safety Workflow (`agency_consultation_*`)
Follows the 3-step verification pattern ensuring agents never submit client inquiries without explicit human confirmation:
1. `agency_consultation_get_form`: Fetches the form schema and options.
2. `agency_consultation_validate`: Dry-run validation of client inputs.
3. `agency_consultation_submit`: Executes submission only when `applicantApproved: true` and a client-generated UUID `submissionId` are provided.

---

## 🔒 Security Posture & Citation Protocol
- **Untrusted Segments**: All transcript passages are enclosed in `<<<UNTRUSTED_TRANSCRIPT_SEGMENT>>>` blocks.
- **Verbatim Citations**: AI agents must cite quotes verbatim with the pre-computed YouTube timestamp link:
  `[Saad ft. Danish Hameed — 14:20](https://youtu.be/BAXktGuJ03g?t=860s)`