> 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/developer-tools/mcp/mcp-reference.md).

# Reference

Technical reference for Kick MCP endpoints, credentials, workspace selection, tool discovery, and common tool examples.

Use this page when you need exact MCP connection values or want to confirm how Kick MCP chooses credentials, workspaces, and available tools. For step-by-step setup, see [Connect custom AI tools](/ai/mcp/connectors/connect-custom-ai-tools.md).

### Hosted MCP endpoint

Remote MCP clients connect to:

```
https://use.kick.co/mcp
```

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:

* **Read-only tools** look up data and run reports without making any changes.
* **Write tools** make changes you approve, like creating a transaction or posting a journal entry.

If your AI client uses OAuth, it requests these as the `mcp:read` and `mcp:write` scopes.

### PAT bearer header

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

```
Authorization: Bearer kick_pat_...
```

{% hint style="warning" %}
Keep PATs out of prompts, source control, and shared docs. Revoke any token you suspect has been exposed.
{% endhint %}

### Workspace selection

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

Workspace-bound PATs auto-inject their bound workspace. The backend injects a default `workspaceId` only when the credential resolves to exactly one workspace. User-scoped PATs and OAuth tokens should pass `workspaceId` explicitly.

### Find available tools

Use the tool list shown by your AI client as the current 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`, `MCP: List Servers`, or the equivalent command in your client.
* Ask a safe 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 examples are not a complete list. Use your MCP client's tool list for the up-to-date names available to your credential.

* `context_browse`: list workspaces and entities the credential can access.
* `context_resolve`: resolve a workspace, entity, or ledger by name.
* `transactions_query`: search, inspect, or summarize transactions.
* `reports_query`: run profit and loss, balance sheet, trial balance, and other reports.
* `activity_query`: list recent activity and audit logs.

Kick MCP tools use portable names, usually lower snake case. The available list can vary by token scope, workspace permissions, and enabled workspace features.

### Safety reminders

* 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 setup examples, see [Connect custom AI tools](/ai/mcp/connectors/connect-custom-ai-tools.md). For more safety detail, see [Permissions and Security](/ai/permissions-and-security.md).


---

# 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/developer-tools/mcp/mcp-reference.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.