MCP Server

Diary Tools exposes an MCP server so AI agents can work with contacts, draft email, and read synced calendar data — without building a custom API client.

There are eight tools. Directory tools return compact rows; get_contact is the full record.

Endpoint


URL	`https://app.diary.tools/api/mcp`
Transport	Streamable HTTP
Server name	`diary-tools`

Authenticate with a Bearer token in the Authorization header.

Authentication

There are two common ways to authenticate:

Agent API keys — create a long-lived key (agt_live_…) in the portal under Subscription → Agents / API keys. Best for OpenClaw and other automation hosts.
Human OAuth — Cognito OAuth (PKCE) for interactive clients such as Claude or MCP Inspector. Use the access JWT as the Bearer token.

Agent keys support presets such as Read Only, User (default for automation), and Admin.

Example config

Portal Integrations → MCP shows a ready-made snippet. A typical OpenClaw-style config looks like:

{
  "mcp": {
    "servers": {
      "diary-tools": {
        "url": "https://app.diary.tools/api/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer agt_live_…"
        }
      }
    }
  }
}

Replace the token with your agent key. Never commit live keys to source control.

IDs

Most contact tools take:

projectId — the project slug (for example personal)
contactId — the contact slug (for example jane-smith)

Use ids from list_contacts, open_threads, or search_contacts when you call get_contact or update_contact.

Compact directory vs full record

list_contacts, open_threads, and search_contacts return compact directory rows only: id, name, email, company, jobTitle, workflowStatus, and location. They omit notes, OSINT findings, previous roles, and other heavy fields so agents do not load the whole database into context.

Call get_contact when you need the full record.

Contact tools

Tool	Inputs	What it does
`list_contacts`	`projectId`; optional `limit` (default 100, max 100), `offset`	Compact directory of contacts in a project
`open_threads`	`projectId`	Contacts with an open email thread (`WaitingOnMe` / `WaitingOnThem`). Compact rows
`search_contacts`	`projectId`, `q` (min 2 characters); optional `limit` (default 20, max 50), `offset`	Fuzzy search by name, company, job title, or email. Compact rows
`get_contact`	`projectId`, `contactId`	Full contact, including notes and OSINT
`update_contact`	`projectId`, `contactId`, `fields`	Patch CRM and OSINT fields. Use `"REMOVE"` or `null` to clear optional fields; `name` and `email` cannot be cleared

Email

Tool	Inputs	What it does
`send_email`	`projectId`, `contactId`, `subject`, `body` (markdown); optional `replyToLatestThread`	Create a Gmail draft to a stored contact (not a raw address). Body is formatted, not rewritten. Returns a Gmail deep link — it does not auto-send

send_email requires Gmail connected on that project. See Connecting Gmail.

Calendar

These tools read data already synced into Diary Tools (not a live Google query). Connect Gmail first so calendar events and availability exist.

Tool	Inputs	What it does
`list_upcoming_calendar_events`	optional `projectId`, optional `to` (ISO datetime or `YYYY-MM-DD`)	Upcoming key events from now. Omit `to` to return all stored upcoming events
`get_availability_slots`	optional `from`, optional `to` (ISO)	Bookable 30-minute free slots within working hours. Defaults to now through the next 4 weeks. Returns `{ timezone, slots: [{ start, end }] }`

Not in MCP

There is no create_contact, delete_contact, or dedicated OSINT-run tool. Add contacts in the portal, via Gmail sync, or the Chrome extension. Run OSINT from the contact page in the portal. Agents read enrichment with get_contact and patch it with update_contact.

Resources

The server also publishes MCP resources agents can read:

URI	Purpose
`skill://diary-tools`	When and how to use the tools
`skill://diary-tools/server-guide`	Auth, setup, IDs, and permissions

Tips

Use list_contacts for the directory, search_contacts to find someone, open_threads for open loops, and get_contact when you need notes or OSINT.
Prefer search_contacts before guessing ids.
List and search responses do not include OSINT.