# 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 %}