Agent patterns

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

MCP gives agents hands on your Karzoun data. These patterns help you get reliable results without repeating yourself in every chat.

For hosted connections (Claude.ai, Manus, remote Cursor), see AI app connectors — same tools, different client config.

Ground the agent first

Add a short system or project instruction so the model knows Karzoun tools exist:

You have Karzoun MCP tools for CRM and workspace data.
- Prefer read tools (customers, tags, customerDetail) before mutations.
- Use page: 1, perPage: 10 for list queries unless I ask for more.
- Confirm destructive actions (customersRemove, tagsRemove) before calling.

Point the agent at this docs site for operation names: tool catalog.

Pattern: Lookup before action

Example prompt: "Find customer with email alice@example.com, show their tags, then add tag VIP if missing."

Pattern: Safe exploration

Start read-only with a tool prefix:

"KARZOUN_MCP_TOOL_PREFIX": "customer"

Or instruct: "Only use query tools for the next five messages."

Use currentUser to verify the token works and see which workspace identity the app runs as.

Pattern: Paginated lists

Agents often fetch unbounded lists and hit the 512 KB response cap.

Good prompt: "List the first 5 customers created this month using page 1 and perPage 5."

Tool args example:

{ "page": 1, "perPage": 5 }

See pagination for pagination.totalCount and hasNextPage.

Pattern: CRM hygiene

Pattern: Webhook inspection

For integration debugging (not provider webhooks):

1. webhooks — list subscriptions
2. webhookDetail — inspect config
3. webhookDeliveryLogs — see failures and HTTP status codes

Pair with the webhooks guide for tenant outbound events.

Pattern: Hosted backend agent

For server-side workers calling /mcp:

1. Store KARZOUN_APP_TOKEN in secrets manager
2. initialize → capture mcp-session-id
3. tools/call in a loop with explicit tool names
4. Log GraphQL errors from tool responses

Do not expose the session or token to end users. Details: Hosted MCP.

Anti-patterns

Custom rules in Cursor

Optional .cursor/rules/karzoun-mcp.mdc:

# Karzoun MCP
- Use Karzoun tools for live CRM data; do not invent customer ids.
- After mutations, summarize what changed and link to relevant record ids.
- On permission errors, tell the user to check Developer → Apps scopes.