> For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kick.co/ai/troubleshooting/mcp-troubleshooting.md). # MCP Troubleshooting Use the symptom that matches what you see. ### The MCP tool list is empty Check these items: * The Kick credential can access the workspace. * The token has `mcp:read` scope for read-only tools. * The relevant Kick feature is enabled for that workspace. * The MCP client was restarted or reconnected after config changes. * The config file uses the client-specific key names, such as `mcpServers`, `servers`, `context_servers`, `url`, or `httpUrl`. Strict MCP clients may require portable lower-snake-case tool names. Kick tools use names such as `transactions_query` and `reports_query`. ### OAuth authorization fails If the AI client's authorization step doesn't complete: * Confirm your Kick session is active in another tab. * Check that your firm has approved the AI client for Kick. On Claude Team and Enterprise plans, an Owner needs to add the connector at the org level before members can connect. On ChatGPT Enterprise and Edu plans, Developer Mode is admin-controlled. * If a previous OAuth session is stuck, remove the connector from the AI client and re-add it before retrying. ### Hosted MCP cannot connect Confirm the URL: ``` https://use.kick.co/mcp ``` For PAT-based setup, confirm the bearer header: ``` Authorization: Bearer kick_pat_... ``` Do not include extra spaces, quotes, or placeholder text in the token value. ### The wrong workspace is active Ask the assistant to list workspaces and confirm the workspace before calling other tools: > List the Kick workspaces I can access. Confirm which workspace is active before looking up client data. For workspace-bound PATs, the bound workspace is injected automatically. For user-scoped PATs and OAuth tokens, pass `workspaceId` in tool calls when a tool requires it. ### Auth or scope errors Verify that the credential has the right access: * Workspace access for the client. * `mcp:read` for read-only tool calls. * `mcp:write` only when a write workflow is approved. If a write action fails, confirm that the user has permission to perform that action in Kick. ### A write tool returns a preview This is expected for preview-first actions. Review the preview and only confirm it if the workspace, resource IDs, dates, amounts, and intended change match your intent. Tell the assistant: > Show me the preview and stop. Do not confirm the action until I approve. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kick.co/ai/troubleshooting/mcp-troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.