# Tjati agent access: full context

> Complete connection and operating context for AI agents using Tjati through MCP.

Last updated: 2026-07-15
Canonical page: https://tjati.com/agent/
Concise guide: https://tjati.com/agent.md

## Service contract

- API base: `https://api.tjati.com`
- MCP endpoint: `https://api.tjati.com/mcp`
- Transport: remote Streamable HTTP MCP
- OAuth protected-resource metadata: `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`
- API documentation index: `https://api.tjati.com/llms.txt`

The versioned OpenAPI path and API-host documentation index are current release publication gates. Do not guess at unpublished schemas. The unversioned OpenAPI path is the current generated surface; the versioned path is intended to become the stable production contract.

## Connection sequence

1. Configure the client with `https://api.tjati.com/mcp`.
2. Use the server's protected-resource metadata to discover OAuth requirements.
3. Complete Tjati sign-in.
4. Inspect the requested installation and scopes.
5. Grant only the smallest scope set needed for the task.
6. Confirm connectivity with a read-only tool.
7. Propose a durable write before executing it unless the member explicitly delegated execution.

## Client quickstarts

### Claude Desktop

Status: documentation-supported; compatibility soak remains a publication gate.

1. Open Settings, choose Customize, open Connectors, and select Add custom connector.
2. Name the connector Tjati and enter `https://api.tjati.com/mcp`.
3. Complete OAuth and review requested Tjati scopes.
4. Ask Claude to list your areas. A read-only result confirms the connection.

### Claude Code

Status: documentation-supported; compatibility soak remains a publication gate.

```sh
claude mcp add --transport http --scope user tjati https://api.tjati.com/mcp
```

Open `/mcp`, select Tjati, complete sign-in, grant the smallest sufficient scopes, then run a read-only Tjati tool.

### Cursor

Status: documentation-supported; compatibility soak remains a publication gate.

```json
{
  "mcpServers": {
    "tjati": {
      "url": "https://api.tjati.com/mcp"
    }
  }
}
```

Save the configuration, complete OAuth, inspect granted scopes, then verify a read-only operation before durable writes.

### OpenClaw

Status: documentation-supported; compatibility soak remains a publication gate.

```sh
openclaw mcp add tjati --url https://api.tjati.com/mcp \
  --transport streamable-http --auth oauth --no-probe
openclaw mcp login tjati
openclaw mcp doctor tjati --probe
```

Verify a read-only tool before enabling background work.

### Hermes

Status: documentation-supported; compatibility soak remains a publication gate.

```yaml
mcp_servers:
  tjati:
    url: "https://api.tjati.com/mcp"
    auth: oauth
```

```sh
hermes mcp login tjati
hermes mcp test tjati
```

Verify a read-only tool before enabling background work.

### ChatGPT

Status: administrator-gated. Availability can vary by workspace, plan, region, and administrator policy.

Where custom remote MCP apps are available, create a Tjati connection using `https://api.tjati.com/mcp`, complete OAuth, review scopes, and test a read-only request. Do not claim compatibility until the workspace exposes the required connection surface.

### Gemini

Status: documentation-supported; compatibility and background-mode soak remain publication gates.

```sh
gemini mcp add --transport http tjati https://api.tjati.com/mcp
/mcp auth tjati
```

Complete OAuth, grant only needed scopes, and verify a foreground read-only tool. Use Tjati schedules and webhooks for background work.

## Authorization behavior

OAuth is the default for interactive clients. A compliant client discovers authorization server information through the protected-resource metadata, opens Tjati sign-in, and returns with a scoped installation.

On `401 Unauthorized`, follow the `WWW-Authenticate` challenge and its `resource_metadata` reference. On `403 Forbidden` or `insufficient_scope`, stop retrying and request the named scope through the authorization flow or ask the supervising member. Never broaden authority silently.

Scoped personal access tokens are permitted only for approved headless hosts:

1. Create an agent installation in Tjati.
2. Grant only required scopes.
3. Issue the key once and store it in a secret manager.
4. Inject it through the runtime environment.
5. Send `Authorization: Bearer <token>` to Tjati only.

Never put a PAT in a repository, client profile, prompt, log, or webhook body. Never pass a Tjati token through to another service. Rotate a key after suspected exposure.

If a refresh token expires or access is revoked, remove the stale client connection and run OAuth again. Reauthorization creates fresh authority and does not restore a revoked key.

## Scope vocabulary

Default grant:

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

Observe and capture:

- `state:read`
- `capture:create`
- `calendar:read`

Plan and act:

- `work:propose`
- `work:execute`

Automate and communicate:

- `automation:manage`
- `communications:draft`

No other scope is grantable. `calendar:write`, `communications:send`, `memory:read` and `memory:write` are not offered: no provider adapter has any calendar event create, update or delete method; sending mail is refused in validation; and the memory pair has no feature behind it.

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.

A scope grants eligibility, not unconditional execution. High-impact operations can still pause for member approval. Prefer proposal authority to execution authority unless the member explicitly asks for autonomous execution.

## Safe execution rules

- Fetch or inspect before modifying.
- State the durable change and its target before asking for stronger authority.
- Use exact resource identifiers returned by Tjati.
- Follow MCP tool schemas or the versioned OpenAPI schema exactly.
- Do not invent fields, endpoints, status values, or error recovery behavior.
- Use idempotency keys where the contract supports them.
- Do not automatically retry a non-idempotent write after an ambiguous timeout.
- Treat `401` as an authorization-discovery event, not a reason to guess credentials.
- Treat `403` or `insufficient_scope` as a stop condition until authority changes.
- Treat revocation as final for the affected credential.
- Preserve human approval boundaries.

## Always-on delivery

Use schedules for durable runs. Use signed webhooks for result delivery. Do not rely on keeping an interactive client session open.

Webhook subscription flow:

1. Generate a 32-byte base64url signing secret and retain it before proposing the subscription.
2. Register an HTTPS endpoint and one or more durable `core.*` event filters.
3. Verify timestamp, delivery ID, event ID, raw body, and HMAC signature before processing.
4. Reject invalid or stale signatures.
5. Use event ID for logical deduplication and delivery ID for attempt-chain evidence.
6. Make every receiver idempotent.

Signature input:

```text
timestamp + "." + deliveryId + "." + eventId + "." + rawBody
```

Replay request shape:

```http
POST /api/v1/webhook-deliveries/{id}/replay
Idempotency-Key: <unique-key>
Content-Type: application/json

{ "reason": "receiver recovered" }
```

Automatic attempts retain one delivery ID. Manual replay is for terminal deliveries and 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 delivery evidence. A request already in flight can still finish remotely.

## Launch and commercial state

- Agent access is bundled into Standard and Max.
- There is no separate agent add-on in this release.
- Usage can be metered for abuse protection and product learning; billing is unchanged.
- Six client flows are documentation-supported but still require compatibility soak before publication.
- ChatGPT custom MCP is administrator-gated.
- The versioned OpenAPI path and API-host `llms.txt` remain publication gates.

## Readiness checklist

- MCP endpoint is reachable.
- OAuth discovery succeeds.
- The installation has only intended scopes.
- A read-only tool succeeds.
- The runtime knows when to propose, ask for approval, or stop.
- Non-idempotent writes are not retried blindly.
- Webhook verification, deduplication, and replay behavior are implemented where applicable.
- Revoked credentials and insufficient scopes stop future protected work.