# MCP Tool Reference

Cakewalk's MCP server exposes 13 tools across three categories: Users, Work Apps and Requests. Each tool requires a specific scope. Your AI assistant only sees tools that match the scopes you authorized during setup.

***

## User Tools

Required scope: `mcp:users.read`

### GetMyUserInformation

Retrieve the profile and access details of the currently authenticated user. Good starting point to confirm who you are in the system.

| Parameter | Required | Description                                     |
| --------- | -------- | ----------------------------------------------- |
| *None*    |          | Uses your authenticated identity automatically. |

**Example prompt:** "What's my user profile in Cakewalk?"

***

### GetUserInformation

Look up a user's profile and access details by their user ID.

| Parameter | Required | Description         |
| --------- | -------- | ------------------- |
| `userId`  | Yes      | The user ID (UUID). |

**Example prompt:** "Get the profile for user ID 3fa85f64-5717-4562-b3fc-2c963f66afa6."

***

### GetUserByEmail

Look up a user's profile and access details by email address. Useful when you know the email but not the ID.

| Parameter | Required | Description        |
| --------- | -------- | ------------------ |
| `email`   | Yes      | The email address. |

**Example prompt:** "Look up <jane@company.com> in Cakewalk."

***

### ListAllUsers

List all users in the organization. Returns a complete roster with profile information.

| Parameter | Required | Description        |
| --------- | -------- | ------------------ |
| *None*    |          | Returns all users. |

**Example prompt:** "Show me everyone in our Cakewalk workspace."

***

### ListUserAccessesByEmails

Check which apps one or more users have access to, looked up by email.

| Parameter | Required | Description                                                           |
| --------- | -------- | --------------------------------------------------------------------- |
| `emails`  | Yes      | Comma separated email addresses (e.g. `alice@acme.com,bob@acme.com`). |

**Example prompt:** "What apps do <alice@acme.com> and <bob@acme.com> have access to?"

***

### ListUsersByWorkAppIds

List all users who have access to one or more apps. Useful for auditing who can access a specific tool.

| Parameter    | Required | Description                                                                                                       |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `workAppIds` | Yes      | Comma separated work app IDs (UUIDs). Use `ListManagedWorkApps` or `SearchTemplatesOrWorkAppsByName` to find IDs. |

**Example prompt:** "Who has access to our Jira instance?" (after finding Jira's work app ID)

***

## App Tools

Required scope: `mcp:workapps.read`

### ListManagedWorkApps

List all apps you manage or have owner responsibility for. Returns app details, related users and groups. This is the main way to discover work app IDs.

| Parameter | Required | Description              |
| --------- | -------- | ------------------------ |
| *None*    |          | Returns apps you manage. |

**Example prompt:** "What apps do I own in Cakewalk?"

***

### SearchTemplatesOrWorkAppsByName

Search the catalog for apps by name. Supports fuzzy matching. Useful when you know an app's name but not its ID.

| Parameter | Required | Description                                         |
| --------- | -------- | --------------------------------------------------- |
| `names`   | Yes      | Comma separated app names (e.g. `Jira,Salesforce`). |

**Example prompt:** "Find Figma and Notion in Cakewalk."

***

### GetWorkAppPermissionLevels

Get the permission tiers (e.g. Viewer, Editor, Admin) for a specific app. Useful before creating an access request.

| Parameter   | Required | Description                                                                                        |
| ----------- | -------- | -------------------------------------------------------------------------------------------------- |
| `workAppId` | Yes      | The work app ID (UUID). Use `ListManagedWorkApps` or `SearchTemplatesOrWorkAppsByName` to find it. |

**Example prompt:** "What permission levels does GitHub have?"

***

### GetWorkAppCustomFields

Get the custom metadata field definitions attached to work apps (e.g. department, cost center, compliance tags).

| Parameter | Required | Description                           |
| --------- | -------- | ------------------------------------- |
| *None*    |          | Returns all custom field definitions. |

**Example prompt:** "What custom fields are set up for our apps?"

***

## Request Tools

### ListRecentRequests

Required scope: `mcp:requests.read`

List the most recent access requests across all apps. Returns request details with related users, apps and policies.

| Parameter | Required | Description              |
| --------- | -------- | ------------------------ |
| *None*    |          | Returns recent requests. |

**Example prompt:** "Show me the latest access requests."

***

### SearchOpenRequests

Required scope: `mcp:requests.read`

Search for pending access requests awaiting approval. At least one filter is required.

| Parameter          | Required | Description                                                     |
| ------------------ | -------- | --------------------------------------------------------------- |
| `workAppIds`       | No       | Comma separated work app IDs (UUIDs) to filter by app.          |
| `createdByUserIds` | No       | Comma separated user IDs (UUIDs) of who submitted the requests. |
| `targetUserIds`    | No       | Comma separated user IDs (UUIDs) of who the requests are for.   |

**Example prompt:** "Are there any open access requests for GitHub?"

***

## Scope Summary

| Scope                | Tools it unlocks                                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `mcp:users.read`     | GetMyUserInformation, GetUserInformation, GetUserByEmail, ListAllUsers, ListUserAccessesByEmails, ListUsersByWorkAppIds |
| `mcp:workapps.read`  | ListManagedWorkApps, SearchTemplatesOrWorkAppsByName, GetWorkAppPermissionLevels, GetWorkAppCustomFields                |
| `mcp:requests.read`  | ListRecentRequests, SearchOpenRequests                                                                                  |
| `mcp:requests.write` | *Reserved for future tools.*                                                                                            |

{% hint style="info" %}
All tools return data scoped to your organization. You can only see users, apps and requests within your Cakewalk workspace.
{% endhint %}


---

# 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://www.cakewalk.security/docs/open-api-and-mcp/introduction-to-mcp/mcp-tool-reference.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.