> 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

Fix common Kick MCP issues with client setup, credentials, workspace selection, empty tool lists, and hosted connections.

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 or an admin with permission to manage connectors needs to add Kick at the org level before members can connect. On ChatGPT Enterprise and Edu, apps are off until an admin enables them; on ChatGPT Business they're on by default, but an admin can turn them off. Either way, the setting is in **Workspace settings** > **Apps**.
* 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kick.co/ai/troubleshooting/mcp-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.