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