# How to work with Desync.

Connect your AI assistant or your own systems to Desync's Catholic data. See what each record holds.

From https://www.desync.ai/docs

## Getting access

You need a Desync account and a plan. Sign up or sign in at crm.desync.ai, or book a call first, as most teams do. Then make a key in your account. One key works for the MCP server and the REST API.

| Way in | What it is for |
| --- | --- |
| MCP server | For AI assistants such as Claude and ChatGPT: every search, saved list and CRM tool. |
| REST API | For developers connecting your own systems: the searches and your history. |
| Observatory | Catholic news. Free for a person to read. Bots and AI assistants need an Observatory API key, which comes with every Starter plan. |

## Sign up and get help

Questions about the API or MCP go to Jackson, one of our co-founders. He builds our data infrastructure.

| Where | What for |
| --- | --- |
| [Sign up or sign in](https://crm.desync.ai/) | Your Desync account, at crm.desync.ai. New accounts start here. |
| [Book a time with Jackson](https://calendly.com/jackson-desync/) | A call about the API, MCP or connecting your own systems. |
| [Email Jackson](mailto:jackson@desync.ai) | jackson@desync.ai |
| [Write to us](https://www.desync.ai/contact) | Anything else, from plans to a dataset we do not hold. |

## Connect over MCP

MCP is an open standard that lets AI assistants such as Claude and ChatGPT use outside tools. Add Desync to yours and it can search our data, keep saved lists and work in your CRM.

Your AI assistant connects to https://mcp.desync.ai/mcp. Sign in with your Desync account, or send a key.

MCP client config:

```json
{
  "mcpServers": {
    "desync": {
      "type": "http",
      "url": "https://mcp.desync.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${DESYNC_API_KEY}"
      }
    }
  }
}
```

1. In Claude or ChatGPT, add a custom connector named Desync.
2. Use https://mcp.desync.ai/mcp as its URL and leave the OAuth client fields blank.
3. Sign in with the Google account on your Desync account.

A key goes in the Authorization header as a bearer token, or in an X-API-Key header. Without a key or a sign-in, the server answers 401 and asks your assistant to sign in. A sign-in lasts 30 days.

## MCP tools

45 tools in four groups. Searches count each row they return against your plan; history, saved lists and CRM tools are free.

### Search: 7 tools, read only

| Tool | What it does |
| --- | --- |
| `church_search` | Parishes by name, place, diocese, language, school and more, with staff and contacts if asked. Up to 100 a call. |
| `church_people_search` | Clergy and parish staff by name, place, role, title, or with an email or phone on record. Up to 200 a call. |
| `church_sponsor_search` | Businesses that advertise in parish bulletins, by place and keyword. Up to 200 a call. |
| `nd_search` | Notre Dame alumni by name. |
| `nd_batch_search` | Many alumni lookups in one call: up to 10 queries, 100 rows in all. |
| `nd_mass_match` | Alumni by any field: class, degree, college, hometown, title. Up to 100 a call. |
| `nd_similar` | The graduates most like one you name, up to 100. |

### History: 1 tool

| Tool | What it does |
| --- | --- |
| `lookup_history` | Records you have already paid for, free to read again. |

### Saved lists: 5 tools

| Tool | What it does |
| --- | --- |
| `list_custom_tables` | Your saved lists. |
| `get_custom_table` | One list, with each entry's outreach status, notes and draft email. |
| `create_custom_table` | Start a list of alumni, parish staff, school staff or sponsors, with or without an outreach pipeline. |
| `add_to_custom_table` | Add records to a list. Duplicates are skipped. |
| `update_custom_table_entry` | Set an entry's status, notes or draft email. |

### CRM: 32 tools

| Tools | What they cover |
| --- | --- |
| Read, 14 tools | People, companies, deals, tasks, notes, custom objects and saved views, plus past emails that worked, as a style guide. |
| Write, 18 tools | Create and update people, companies, deals, tasks, notes, custom records and views. |
| What it never does | Delete anything, send email, change your schema or manage your team. Those stay in the CRM, with you. |

## REST API

JSON in and out: every call is a POST to https://mcp.desync.ai/api, with the same key. 50 rows by default, 200 at most. Errors come back as {"error": "..."} with status 400, 401 or 429.

### Endpoints

| Endpoint | What it returns |
| --- | --- |
| `/church/search` | Parishes, with staff and contacts if you ask for them. |
| `/church/people-search` | Clergy and parish staff. |
| `/church/bulletins` | A parish's bulletins, with their events, programs, people and sponsors. |
| `/nd/search` | Notre Dame alumni by any field. |
| `/nd/similar` | The graduates most like one you name. |
| `/history` | Records you already looked up. Free. |
| `/custom-tables` | Your saved lists. Free. |
| `/custom-tables/entries` | The entries in one list. Free. |

Pastors in Illinois:

```shell
curl -X POST https://mcp.desync.ai/api/church/people-search \
  -H "Authorization: Bearer YOUR_DESYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"state": "IL", "clergy_category": "Pastor"}, "limit": 25}'
```

50 requests a minute per address; past that, status 429. Schools and hospitals are searched in the Desync app, not yet through the API or MCP.

## Observatory

Catholic news, read around the clock and linked to the people and places in it. Free for a person to read. Bots and AI assistants reach its MCP server at https://api.observatory.desync.ai/mcp with an Observatory API key, which comes with every Starter plan.

Add it to Claude Code:

```shell
claude mcp add --transport http desync-observatory \
  https://api.observatory.desync.ai/mcp \
  --header "X-API-Key: YOUR_OBSERVATORY_API_KEY"
```

### 6 tools

| Tool | What it does |
| --- | --- |
| `search_articles` | Stories by keyword and meaning, up to 25, with English titles and summaries. |
| `get_article` | One story's English text. |
| `list_entities` | People, organizations and places the news mentions. |
| `entity_graph` | What one of them is linked to, two steps out at most. |
| `list_sources` | Every source Observatory reads. |
| `get_stats` | How much it has read. |

## What a record holds

| Set | What a row holds |
| --- | --- |
| Parishes | Name, address, diocese, status, languages, year founded, website. Open one for Mass and confession times, sacraments, ministries, outreach, events, facilities, its school, and its bulletins. |
| Parish staff and clergy | Name, role, title, email, phone, office hours, and the parish that lists them. |
| Bulletin advertisers | Business, category, phone, email, address, website, and the parish bulletin it advertises in. |
| Catholic schools | Type, grades, enrollment, class size, tuition, accreditation, year founded, staff. In the Desync app, not yet the API or MCP. |
| School faculty and staff | Name, title, department, email, phone, profile, school. In the Desync app, not yet the API or MCP. |
| Catholic hospitals | Health system, type, trauma level, licensed beds, Catholic sponsor, diocese, departments. In the Desync app, not yet the API or MCP. |
| Hospital clinicians and staff | Name, credentials, specialty, provider number, phone, languages, accepting new patients, practice location. In the Desync app, not yet the API or MCP. |
| Notre Dame alumni | Name, class year, degree, major, college, honors, hometown, current title. |
| Catholic news | Title, summary, link, source, date, language, tags, and the people, organizations and places in it. |

## How current it is

Catholic news comes in every day: Observatory reads it around the clock. The other sets are gathered from their sources in passes: parishes from their websites and weekly bulletins, schools and hospitals from theirs. Every set is re-counted on a schedule.

| Set | Re-counted |
| --- | --- |
| Parishes | Monthly |
| Dioceses | Quarterly |
| Catholic schools | Monthly |
| Catholic hospitals | Monthly |
| Bulletin advertisers | Monthly |
| Parish staff and clergy | Monthly |
| School faculty and staff | Monthly |
| Hospital clinicians and staff | Monthly |
| Notre Dame alumni | Quarterly |
| Catholic news | Weekly |

We use public records and the data you bring. Nothing else.