# 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_find` and `reports_profit_loss_get`.

### 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.

### The assistant cannot start local MCP

Check that the `kick` binary is available:

```
kick --help
```

If it is not on `PATH`, update the MCP config to use the absolute path to the installed or built Kick binary.

For local stdio, the command should be:

```
{
    "command": "kick",
    "args": ["mcp", "serve"]
}
```

Restart the MCP client after editing config.

### 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 local MCP, bind the session to a workspace:

```
kick --workspace <workspace-id> mcp serve
```

If you use CLI profiles, check the selected profile and its default workspace.

### 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: 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:

```
GET https://docs.kick.co/developers/mcp-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.