AI Agent Integration Guide

This is the canonical starting point when a person asks an AI assistant to connect to Leenops.

Never ask the user to paste an API key into chat. Ask them to create a least-privilege key and save it through their AI client's secret, environment-variable, or MCP configuration interface.

Canonical URLs

Purpose	URL
Documentation	`https://docs.leenops.com/docs/api`
Agent guide	`https://docs.leenops.com/docs/api/agent-guide`
REST API	`https://workspace.leenops.com/api/v1`
Hosted MCP API	`https://workspace.leenops.com/api/mcp`
OpenAPI status	`https://docs.leenops.com/docs/api/openapi`
Short machine index	`https://docs.leenops.com/llms.txt`
Complete agent bundle	`https://docs.leenops.com/llms-full.txt`
Integration support	`support@leenops.com`

Use the workspace.leenops.com origin directly. The apex and www origins are marketing surfaces, and some clients remove Authorization while following a cross-host redirect.

Choose the integration surface

Need	Use	Why
Let an AI assistant inspect and act on Leenops	MCP	Live tool schemas and permissions are discoverable per key
Build a conventional service against a field-documented endpoint	REST	Stable resource-oriented HTTP contract
Need an operation absent from the public status page	MCP or stop	An unlisted application route is not a supported external contract
Receive events	Module webhook	Signed, asynchronous delivery
Run a short human-approved evaluation	Agent trial	Guarded tool allowlist, expiry, and quota

For broad agent automation, MCP is the recommended surface. The REST status status page lists only the supported public REST contract. OpenAPI publication is temporarily paused; do not use a cached specification or probe unlisted application routes.

MCP integration protocol

Follow these steps in order:

Ask an Admin or Owner to open Settings > AI > External Connections > API Keys.
Create a separate temporary key for this integration.
Grant the smallest relevant preset or scope set and set an expiry for testing.
Configure leenops-mcp using the client's secret/configuration mechanism.
Verify the key with GET /api/mcp/session.
Retrieve live schemas with GET /api/mcp/tools/list?includeDenied=true&includeSchemas=true.
Choose a tool from allowedToolNames; never invent a tool name or argument.
Run a read-only tool first.
Explain the exact impact before any write, even when the MCP client does not provide a confirmation UI.
Use disposable records for mutation tests, clean them up, and revoke the temporary key.

Pin the currently verified public package during reproducible tests:

npx -y leenops-mcp@2.0.4 \
  --api-key="$LEENOPS_API_KEY" \
  --api-url="https://workspace.leenops.com"

See MCP setup for client-specific configuration and Tool Discovery for the hosted endpoints.

REST integration protocol

Confirm that the intended operation is listed in Public API Status.
Read its endpoint guide. Do not derive fields from a route name.
Create a key with the documented scope.
Send a read-only request and record its response envelope.
Test validation with a disposable request.
For writes, identify whether the action is reversible, soft-delete, or permanent.
Add bounded retries only for network errors, 429, and retryable 5xx.
Do not retry 400, 401, 403, 404, or 422 unchanged.
Honor Retry-After and make retryable mutations idempotent in the caller.
Remove test data and revoke the temporary key.

If an operation is not listed, use an equivalent permitted MCP tool or email support. Do not guess a body from database fields, UI labels, or another module.

Authentication and secret handling

API keys start with wks_ and are workspace-bound:

Authorization: Bearer wks_example

The key must not appear in:

chat messages or prompts;
screenshots or screen recordings;
source code or committed .env files;
query strings or URLs;
support tickets or webhook payloads;
logs, traces, or analytics.

Use one key per integration. Rotation means creating a replacement, testing it, and revoking the old key.

Pre-write safety check

Before an agent writes, it must be able to answer:

Which workspace will change?
Which tool or HTTP operation will run?
Which records and fields will change?
Is the operation reversible?
Is a duplicate request safe?
What permission authorizes it?
How will the result be verified?
How will test data be removed?

If any answer is unknown, stop and retrieve the live schema, read the endpoint guide, or contact support.

Error decision

Result	Agent action
`400` / `422`	Correct the request using the documented/live schema; do not blindly retry
`401`	Verify secret storage, bearer format, expiry, revocation, and canonical host
`403`	Inspect scopes/permissions; do not request broader access without explaining why
`404`	Verify resource ID, workspace ownership, path, and whether the route/tool exists
`409`	Read the conflict response and current resource state before deciding
`429`	Honor `Retry-After`; use exponential backoff with jitter
`5xx`	Retry only safe/idempotent operations within a bounded budget
Missing MCP tool	Check `/api/mcp/session`, denied tools, features, and `--read-only`
Ambiguous contract	Stop; do not infer fields

See Troubleshooting for detailed diagnostics.

Escalate to Leenops

Email support@leenops.com with:

workspace ID, never the API key;
UTC timestamp;
REST method/path or MCP tool name;
HTTP status;
request, delivery, or correlation ID when present;
sanitized input and response body;
client and leenops-mcp version;
whether the failure is reproducible;
expected and actual behavior.

Redact credentials, personal data not required for diagnosis, attachment URLs, and capability tokens.

Definition of done

An integration is ready when:

the key is least-privilege and separately revocable;
authentication and a read-only smoke test pass;
all used schemas are documented or retrieved live;
writes were tested against disposable data;
401, 403, 429, and retryable 5xx behavior were exercised;
duplicate delivery/call behavior is safe;
logs contain no secrets;
cleanup and key rotation are documented.

AI Agent Integration Guide

On this page