Advanced Setup

Connect Cursor, Gemini CLI, Perplexity, generic MCP clients, or a local Kick CLI server, plus reference details on PATs, scopes, credentials, and tool discovery.

For most accountants, the MCP Quickstart covers what you need. Use this page when you're connecting an AI client other than Claude or ChatGPT, when your client requires a JSON config file, or when you need the full reference on PATs, OAuth scopes, credential lookup, and workspace selection.

The hosted MCP endpoint is the same regardless of client:

https://use.kick.co/mcp

Config-file setup

Use this section when your client requires a JSON config or when an admin is preparing a repeatable setup.

Cursor

For local stdio, add Kick to ~/.cursor/mcp.json or a project .cursor/mcp.json:

{
    "mcpServers": {
        "kick": {
            "command": "kick",
            "args": ["mcp", "serve"],
            "env": {
                "KICK_PAT": "kick_pat_replace_me"
            }
        }
    }
}

For hosted HTTP:

{
    "mcpServers": {
        "kick": {
            "url": "https://use.kick.co/mcp",
            "headers": {
                "Authorization": "Bearer kick_pat_replace_me"
            }
        }
    }
}

Reload Cursor after changing MCP configuration.

Claude Desktop or Claude Code

Claude local MCP configuration uses an mcpServers object:

{
    "mcpServers": {
        "kick": {
            "command": "kick",
            "args": ["mcp", "serve"],
            "env": {
                "KICK_PAT": "kick_pat_replace_me"
            }
        }
    }
}

Restart Claude after changing the configuration. If your Claude plan supports remote custom connectors, prefer the UI flow in the MCP Quickstart.

Generic MCP clients

For local stdio:

{
    "command": "kick",
    "args": ["mcp", "serve"],
    "env": {
        "KICK_PAT": "kick_pat_replace_me"
    }
}

For remote HTTP, point the client at https://use.kick.co/mcp with bearer authentication:

Authorization: Bearer kick_pat_...

---

PATs and OAuth scopes

Kick MCP supports two authentication methods.

PAT bearer header

For PAT-based clients, send the token as a bearer header:

Authorization: Bearer kick_pat_...

Important: Keep PATs out of prompts, source control, and shared docs. Revoke any token you suspect has been exposed.

OAuth scopes

OAuth-capable clients can discover Kick's protected resource metadata at:

https://use.kick.co/.well-known/oauth-protected-resource

Kick MCP has two kinds of tools, each with its own OAuth scope:

• Read-only tools — mcp:read scope. Used for tool discovery and any call that only looks up data.

• Write tools — mcp:write scope. Used for any call that creates or updates data. Kick previews the change before confirming it.

---

Credential lookup order

The local MCP server resolves credentials the same way as the Kick CLI:

1. --token <value>

2. KICK_PAT

3. KICK_API_TOKEN

4. OS keychain from kick login

5. ~/.config/kick/credentials

KICK_API_TOKEN is the older environment variable name. Prefer KICK_PAT.

---

Workspace selection

Workspace-scoped MCP tools can receive workspaceId in tool arguments.

If local kick mcp serve does not receive workspaceId from the client, it falls back to:

1. --workspace <id>

2. The active profile's defaultWorkspaceId

For remote PAT sessions, workspace-bound PATs inject their bound workspace by default. User-scoped PATs and OAuth tokens should pass workspaceId.

---

Find available tools

Use the tool list shown by your AI client as the source of truth. Available Kick tools can vary by token scope, workspace permissions, enabled features, and client cache state.

Common ways to inspect tools:

• Open the client's MCP, tools, or connector panel and look for the Kick server.

• Use a client command such as /mcp list or MCP: List Servers.

• Ask a read-only prompt:

List the Kick tools you can use. Identify which ones are read-only, then confirm the active workspace before looking up any client data.

If a tool was recently added or renamed, restart or reconnect the MCP client so it reloads the tool list.

---

Common tool examples

These are not a complete list. Use your client's tool list for the up-to-date names available to your credential.

• workspaces_list — list workspaces the credential can access.

• workspaces_get — inspect a specific workspace.

• transactions_find — search transactions with filters.

• transactions_get — inspect a specific transaction.

• reports_profit_loss_get — pull a profit and loss report.

• reports_balance_sheet_get — pull a balance sheet.

• reports_trial_balance_get — pull a trial balance.

• activity_list — list recent activity.

Kick MCP tools use portable lower-snake-case names.

---

Safety

• Use read-only access for lookup and reporting.

• Use write access only when the workflow needs it.

• Confirm workspace and entity IDs before using an assistant on client data.

• Treat assistant output as a draft until an accountant reviews it.

For deeper safety detail, see → Permissions and Security. For setup verification and example prompts, see → MCP Quickstart.