{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["integrationSummary"]},"type":"markdown"},"seo":{"title":"Connect KlickTipp with Claude or Codex via MCP","description":"Official KlickTipp API documentation. Learn how to authenticate, integrate external systems, and build reliable automations using the KlickTipp API.","lang":"en-US","siteUrl":"https://developers.klicktipp.com","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"IntegrationSummary","attributes":{"contract":{"purpose":"Explain how to install and connect the local KlickTipp MCP server so an AI coding assistant can use KlickTipp tools safely.","requiredEndpoints":["POST /account/login","GET /tag","GET /list"],"decisionRules":["Use the ready-made KlickTipp MCP server for standard local AI tooling workflows.","Keep the initial setup read-only until login and metadata inspection work reliably."],"failureHandling":["Verify the repository path, runtime, MCP client configuration, and local .env placement before retrying.","Do not enable write tools until the read-only checks succeed."],"knownLimits":["This setup depends on a local machine, local .env handling, and an MCP-capable client.","Username and password setup is not the right model for partner-grade multi-tenant integrations."],"relatedDocs":[{"label":"Management API Authentication","href":"/guides/management-api-authentication"},{"label":"Error Handling and Validation","href":"/guides/error-handling"}]}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"connect-klicktipp-with-claude-or-codex-via-mcp","__idx":0},"children":["Connect KlickTipp with Claude or Codex via MCP"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this guide to connect your local AI assistant such as Claude or Codex to your KlickTipp account through a local MCP server. This lets your agent inspect KlickTipp structures, work with KlickTipp Management API tools, and help you manage your contacts faster."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before You Start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prepare the following before you start:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to a KlickTipp account with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/management-api-authentication"},"children":["username & password"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Installed local agent like Claude Code or local Codex clients"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You do not need to manually check every technical requirement for the installation upfront. Your AI coding assistant should read the MCP server repository and check the current requirements for you."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-by-step-setup","__idx":2},"children":["Step-by-step setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow this simple recommended setup to use a KlickTipp Connection in your Coding Agent."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"install-the-mcp-server","__idx":3},"children":["Install the MCP server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open a new chat in Claude or Codex to install the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/klicktipp/klicktipp-mcp-binary"},"children":["binary KlickTipp MCP"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste this prompt:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Please set up the KlickTipp MCP server from the published release:\nhttps://github.com/klicktipp/klicktipp-mcp-binary\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Approve only the actions needed to read and clone the repository, create the local ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file, and run read-only tests. Do not approve publishing, committing, deleting files, or enabling write tools during setup."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your agent supports local permission rules, add a deny rule for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," before filling in credentials so the agent cannot read or print that file later. Keep the rule narrow so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.example"]}," stays readable."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"connect-to-klicktipp","__idx":4},"children":["Connect to KlickTipp"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the Installation, check the settings and your connection to KlickTipp."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file is your local settings file. The KlickTipp MCP server uses it to read your KlickTipp username and password. For safety, open this file yourself and enter your credentials manually outside the AI chat session."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the created ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file yourself in your local editor. Do not ask the AI assistant to open the file after credentials have been added."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Show me the path to the generated .env file. Do not print the file contents.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not replace the whole file. Enter username & password directly into the local ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file. Do not paste KlickTipp credentials into the chat."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"dotenv","header":{"controls":{"copy":{}}},"source":"KT_AUTH_MODE=session\nKT_USERNAME=your-klicktipp-username\nKT_PASSWORD=your-klicktipp-password\n","lang":"dotenv"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save your changes in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep this file local. Do not commit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," to Git."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The repository already keeps ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," out of Git and documents the same setup guardrails in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AGENTS.md"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"test-the-connection","__idx":5},"children":["Test The Connection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the connection is configured, restart your AI assistant and open a new chat."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Test the connection via some example Prompts:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"List my KlickTipp tags.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"List my KlickTipp fields.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"List my KlickTipp opt-in processes.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If these read-only tests fail, fix the setup before enabling any write tools."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enable-write-tools","__idx":6},"children":["Enable Write Tools"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enable the write tools only after read-only tools work. Write tools can change data in your KlickTipp account. Keep destructive tools disabled."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Update setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KT_ENABLE_WRITES"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file and save your changes:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"dotenv","header":{"controls":{"copy":{}}},"source":"KT_TOOL_MODE=full\nKT_ENABLE_WRITES=true\nKT_ENABLE_DESTRUCTIVE=false\n","lang":"dotenv"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restart your AI coding assistant after changing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":7},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the AI assistant cannot start the MCP server, ask it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Please inspect the MCP server logs, verify node -v and npm -v, check the .env file, and confirm that the MCP client points to the correct absolute path.\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If authentication fails, check:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KT_AUTH_MODE=session"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KT_USERNAME"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KT_PASSWORD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Whether the account can log in normally"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Whether the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file is in the MCP server repository folder"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-build-your-own-mcp-server","__idx":8},"children":["Advanced: Build Your Own MCP Server"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The binary KlickTipp MCP server is the recommended setup for most users."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build your own MCP server only if the KlickTipp API documentation has changed, the binary server does not support the API tools you need, or you want to experiment with a custom implementation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste following Prompt in a new chat and start building:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Build a local MCP server for KlickTipp from the current KlickTipp developer documentation.\n\nUse these sources as the source of truth:\n- https://developers.klicktipp.com/guides\n- https://developers.klicktipp.com/management-api\n- https://developers.klicktipp.com/guides/management-api-authentication\n- https://developers.klicktipp.com/guides/management-api\n\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"advanced-partner-authentication","__idx":9},"children":["Advanced: Partner Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For partner, production, or customer-facing multi-account integrations, do not use username/password setup. Use Developer Key plus Customer Key authentication instead: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/management-api-authentication"},"children":["Management API authentication"]},"."]}]},"headings":[{"value":"Connect KlickTipp with Claude or Codex via MCP","id":"connect-klicktipp-with-claude-or-codex-via-mcp","depth":1},{"value":"Before You Start","id":"before-you-start","depth":2},{"value":"Step-by-step setup","id":"step-by-step-setup","depth":2},{"value":"Install the MCP server","id":"install-the-mcp-server","depth":3},{"value":"Connect to KlickTipp","id":"connect-to-klicktipp","depth":3},{"value":"Test The Connection","id":"test-the-connection","depth":3},{"value":"Enable Write Tools","id":"enable-write-tools","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Advanced: Build Your Own MCP Server","id":"advanced-build-your-own-mcp-server","depth":2},{"value":"Advanced: Partner Authentication","id":"advanced-partner-authentication","depth":2}],"frontmatter":{"title":"Connect KlickTipp with Claude or Codex via MCP","contract":{"purpose":"Explain how to install and connect the local KlickTipp MCP server so an AI coding assistant can use KlickTipp tools safely.","requiredEndpoints":["POST /account/login","GET /tag","GET /list"],"decisionRules":["Use the ready-made KlickTipp MCP server for standard local AI tooling workflows.","Keep the initial setup read-only until login and metadata inspection work reliably."],"failureHandling":["Verify the repository path, runtime, MCP client configuration, and local .env placement before retrying.","Do not enable write tools until the read-only checks succeed."],"knownLimits":["This setup depends on a local machine, local .env handling, and an MCP-capable client.","Username and password setup is not the right model for partner-grade multi-tenant integrations."],"relatedDocs":[{"label":"Management API Authentication","href":"/guides/management-api-authentication"},{"label":"Error Handling and Validation","href":"/guides/error-handling"}]},"seo":{"title":"Connect KlickTipp with Claude or Codex via MCP"}},"lastModified":"2026-07-21T15:49:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/local-mcp-server","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}