# Tjati agent access

> Connect an AI agent to Tjati through remote MCP. Use explicit OAuth scopes, verify authority before writes, and keep durable work auditable.

Last updated: 2026-07-15

## Recommended path

1. Read this guide before connecting.
2. Connect to `https://api.tjati.com/mcp` with a remote Streamable HTTP MCP client.
3. Discover authorization metadata at `https://api.tjati.com/.well-known/oauth-protected-resource/mcp`.
4. Complete OAuth and request the smallest sufficient scope set.
5. Run a read-only operation before proposing or executing durable work.
6. Treat tool schemas and the versioned OpenAPI document as the operation contract.

## Canonical resources

- Full context: `https://tjati.com/llms-full.txt`
- Documentation index: `https://tjati.com/llms.txt`
- Human portal: `https://tjati.com/agent/`
- MCP endpoint: `https://api.tjati.com/mcp`
- OAuth discovery: `https://api.tjati.com/.well-known/oauth-protected-resource/mcp`
- Versioned OpenAPI: `https://api.tjati.com/openapi/v1.json`
- Current OpenAPI: `https://api.tjati.com/openapi.json`

The versioned OpenAPI path and API-host `llms.txt` are release publication gates. Do not infer an endpoint or schema when a canonical resource is unavailable.

## Authorization

OAuth is the default for interactive clients. A compatible MCP client should use the protected-resource metadata advertised by the server, open Tjati sign-in, and return with a scoped installation.

For a `401 Unauthorized` response, follow the server's `WWW-Authenticate` challenge and protected-resource metadata. For `403 Forbidden` or `insufficient_scope`, do not repeatedly retry. Request the required scope through the documented authorization flow or ask the supervising member.

Scoped personal access tokens are a fallback for approved headless hosts. Store a PAT in a secret manager and inject it through the runtime environment. Never put a PAT in a repository, client profile, prompt, log, or webhook body. Never pass a Tjati token through to another service.

## Least-privilege scopes

Start with:

- `state:read`
- `capture:create`
- `work:propose`

Other grantable scopes:

- Observe and capture: `calendar:read`
- Plan and act: `work:execute`
- Automate and communicate: `automation:manage`, `communications:draft`

A scope makes an operation eligible. It does not guarantee execution. High-impact operations can still pause for member approval.

The two draft tools are member-session only. They write to a real mailbox and have no durable change-set adapter, so an agent actor calling one is refused with `AgentMutationUnsupportedError`. A granted agent can still call the read-only connection-list tool. Do not present drafting as something an agent can do.

## Safe operating rules

- Prefer reads before writes.
- Use `work:propose` before `work:execute` when the member has not explicitly delegated execution.
- Explain the intended durable change before requesting stronger authority.
- Do not silently broaden scope after an authorization failure.
- Follow the current tool schema or versioned OpenAPI contract exactly.
- Supply an idempotency key where the contract accepts one.
- Do not automatically retry a non-idempotent write after an ambiguous timeout.
- Preserve delivery and event identifiers for audit and deduplication.
- Treat human approval boundaries as part of the contract.

## Always-on work

Use Tjati schedules for durable runs. Use signed webhooks for result delivery. Do not keep a client session alive as a substitute for an always-on contract.

For each webhook delivery:

1. Verify the timestamp, delivery ID, event ID, raw body, and HMAC signature before processing.
2. Reject stale or invalid signatures.
3. Use the event ID for logical deduplication.
4. Use the delivery ID for attempt-chain evidence.
5. Make receivers idempotent.

Manual replay creates a new auditable delivery chain linked to the original. Revoking an installation or qualifying grant disables future subscriptions and schedules, cancels queued work where possible, and preserves terminal evidence. A request already in flight may still finish remotely.

## Client support state

Documentation-supported connection flows exist for Claude Desktop, Claude Code, Cursor, OpenClaw, Hermes, and Gemini. End-to-end compatibility soak remains a publication gate.

ChatGPT custom MCP availability can depend on workspace, plan, region, and administrator policy. Treat it as administrator-gated and verify availability before presenting it as a usable path.

## Completion check

A connection is ready only when all of the following are true:

- The client can reach the MCP endpoint.
- OAuth discovery and sign-in complete successfully.
- The installation shows the intended scopes and no unnecessary scopes.
- A read-only Tjati tool succeeds.
- Durable writes remain approval-gated unless execution authority was explicitly granted.
- The runtime has a defined response to revocation, insufficient scope, timeout, and duplicate delivery.