{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-mcp-server/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["callout"]},"type":"markdown"},"seo":{"title":"Agent patterns","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"agent-patterns","__idx":0},"children":["Agent patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["MCP gives agents ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["hands"]}," on your Karzoun data. These patterns help you get reliable results without repeating yourself in every chat."]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"tip","title":"Screenshot placeholder"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Coming soon: screenshot of an agent listing customers and applying tags via Karzoun MCP tools."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["hosted"]}," connections (Claude.ai, Manus, remote Cursor), see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/setup/ai-connectors"},"children":["AI app connectors"]}," — same tools, different client config."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ground-the-agent-first","__idx":1},"children":["Ground the agent first"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add a short system or project instruction so the model knows Karzoun tools exist:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"You have Karzoun MCP tools for CRM and workspace data.\n- Prefer read tools (customers, tags, customerDetail) before mutations.\n- Use page: 1, perPage: 10 for list queries unless I ask for more.\n- Confirm destructive actions (customersRemove, tagsRemove) before calling.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Point the agent at this docs site for operation names: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/tools/_generated/catalog"},"children":["tool catalog"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-lookup-before-action","__idx":2},"children":["Pattern: Lookup before action"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Step"},"children":["Step"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tool"},"children":["Tool"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why"},"children":["Why"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customers"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchValue"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Find the right record"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerDetail"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full context (tags, owner, custom fields)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customersEdit"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagsTag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mutate with confidence"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example prompt:"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"Find customer with email alice@example.com, show their tags, then add tag VIP if missing.\""]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-safe-exploration","__idx":3},"children":["Pattern: Safe exploration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start read-only with a tool prefix:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"KARZOUN_MCP_TOOL_PREFIX\": \"customer\"\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or instruct: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"Only use query tools for the next five messages.\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currentUser"]}," to verify the token works and see which workspace identity the app runs as."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-paginated-lists","__idx":4},"children":["Pattern: Paginated lists"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Agents often fetch unbounded lists and hit the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["512 KB response cap"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Good prompt:"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"List the first 5 customers created this month using page 1 and perPage 5.\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tool args example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"page\": 1, \"perPage\": 5 }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/guides/pagination"},"children":["pagination"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination.totalCount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasNextPage"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-crm-hygiene","__idx":5},"children":["Pattern: CRM hygiene"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Goal"},"children":["Goal"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tools"},"children":["Tools"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dedupe check"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customers"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchValue"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerDetail"]}," on candidates"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merge"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customersMerge"]}," (confirm with user first)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tag campaigns"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tags"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagsTag"]}," on customer ids"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Product lookup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["products"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productDetail"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-webhook-inspection","__idx":6},"children":["Pattern: Webhook inspection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For integration debugging (not provider webhooks):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooks"]}," — list subscriptions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookDetail"]}," — inspect config"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookDeliveryLogs"]}," — see failures and HTTP status codes"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pair with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/guides/webhooks"},"children":["webhooks guide"]}," for tenant outbound events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pattern-hosted-backend-agent","__idx":7},"children":["Pattern: Hosted backend agent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For server-side workers calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/mcp"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KARZOUN_APP_TOKEN"]}," in secrets manager"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize"]}," → capture ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcp-session-id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tools/call"]}," in a loop with explicit tool names"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log GraphQL errors from tool responses"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not expose the session or token to end users. Details: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/setup/hosted"},"children":["Hosted MCP"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"anti-patterns","__idx":8},"children":["Anti-patterns"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Avoid"},"children":["Avoid"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Do instead"},"children":["Do instead"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Do everything with Karzoun\" (vague)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name tools or outcomes: \"list open tags\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Huge ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["perPage"]}," on first call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Start with 5–20 rows"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mutations without confirmation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask agent to propose, then execute"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Embedding tokens in Cursor rules"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keep tokens in MCP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["env"]}," or server secrets"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Using MCP in frontend JavaScript"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GraphQL from backend, or hosted MCP server-side only"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"custom-rules-in-cursor","__idx":9},"children":["Custom rules in Cursor"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".cursor/rules/karzoun-mcp.mdc"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Karzoun MCP\n- Use Karzoun tools for live CRM data; do not invent customer ids.\n- After mutations, summarize what changed and link to relevant record ids.\n- On permission errors, tell the user to check Developer → Apps scopes.\n","lang":"markdown"},"children":[]}]},"headings":[{"value":"Agent patterns","id":"agent-patterns","depth":1},{"value":"Ground the agent first","id":"ground-the-agent-first","depth":2},{"value":"Pattern: Lookup before action","id":"pattern-lookup-before-action","depth":2},{"value":"Pattern: Safe exploration","id":"pattern-safe-exploration","depth":2},{"value":"Pattern: Paginated lists","id":"pattern-paginated-lists","depth":2},{"value":"Pattern: CRM hygiene","id":"pattern-crm-hygiene","depth":2},{"value":"Pattern: Webhook inspection","id":"pattern-webhook-inspection","depth":2},{"value":"Pattern: Hosted backend agent","id":"pattern-hosted-backend-agent","depth":2},{"value":"Anti-patterns","id":"anti-patterns","depth":2},{"value":"Custom rules in Cursor","id":"custom-rules-in-cursor","depth":2}],"frontmatter":{"title":"Agent patterns","titleTranslationKey":"sidebar.mcp.agentPatterns","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Agent patterns"}},"lastModified":"2026-06-23T14:20:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/mcp-server/guides/agent-patterns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}