Approval Studio MCP Server Documentation

2026, © Approval Studio, v. 0.10 alpha

Introduction

Model Context Protocol (MCP) is a standardized framework developed by Anthropic; it enables AI models to seamlessly connect with external tools and data sources without requiring custom integrations for each platform. By serving as a universal protocol, MCP ensures that AI applications can access real-time, contextually relevant data in a secure, scalable and efficient way.

From practical point of view, MCP is a (network) service you may connect to to be able to work using an AI model with an external or local resource; in this case this resource is Approval Studio.

You connect the MCP and manage Approval Studio, querying data and make changes.

For example, you may ask "Find me projects created in May 2025 and enumerate all the assets in them" or "Create a new project, name it 'Flyer for school' and create an upload task assigned on [email protected]".

You may also ask AI to help in understanding Approval Studio concepts, troubleshooting etc like you do asking a customer service person.

The MCP is build around the Approval Studio’s GraphQL API, so please refer the documentation to see what exactly you can do with the system using MCP.

Getting Started

Before using the MCP, you must authenticate with your Approval Studio credentials. The server handles token management automatically, but you’ll need to provide your credentials.

Approval Studio MCP uses bearer token to authenticate.

Every AI client, like Claude, that allows to configure external MCP, should be provided with the bearer token.

For Claude Windows/Mac the configuration looks like this:

{
  "mcpServers": {
		"ApprovalStudio": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://mcp.approval.studio",
			    "--header",
        		"Authorization:${AUTH_HEADER}"			
			],
			"env": {
				"AUTH_HEADER": "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
			}
		}
	}
}

You may find it in Settings->Developer->Local MCP servers->Edit Config

The bearer token is the same you use in REST API or GraphQL API so you may user one of the to generate token.

So having the auth token provided, MCP will interact with the system using the user account provided in the token, and, therefore, all the MCP activities you may see in the timeline or proof report will as activities of the authenticated user.

Core Concepts

Having MCP connected, you can use natural language interacting with Model by asking questions related to general principles, like asking a support people, querying data, statistics, and making changes.

Sample prompts:

Show me 10 most recent created projects.

What new assets were uploaded to the system for the last 3 days?

What assets were approved and rejected since last Friday?

Are there any active projects that are stuck? (no updates for the last couple of dates).

Create a new project, name it “Magazine cover design” and upload an asset from URL “https://address.com/design.pdf”

Find a project “Magazine cover design”, take the assets and requirements from the reference docs and create a detailed report how the assets follows the requirements.

Note: Working with files might be tricking due possible restrictions of the model or client. Generally accepted restriction is 1Mb, but can vary depends of the model and client. This MCP compresses images downloaded from the Approval Studio to fit in this limit (only .jpeg and .png).

Additionally, workflow engines like Zapier or n8n provide additional security restrictions and, usually, refuse to load files from any external sources.

If you use MCP to build a flow there you need to deal with the restrictions by uploading files to some internal storage or smth like this.

Available Tools

Approval Studio organizes work around these key entities:

Projects	Container for all design work, assets, tasks, and documents.
Assets	Design files (PDF, images, videos) that need review and approval.
Tasks	Work assignments for uploading, reviewing, or approving assets.
Reference Documents	Supporting materials like requirements, standards, or examples.
Users	Team members who own projects or are assigned tasks.
Workflows	Automated approval processes.

Note: Many of the sample prompts require a context; for example a prompt Get the review status for asset XYZ789 requires that the project this asset belongs to is provided somewhere earlier, so that the model would know it.

Project Management

List Projects

Retrieves a list of projects with optional filtering by date range, state, metadata, or search query.

Sample prompts:

“Show me all my active Approval Studio projects”

“List projects created in the last week”

“Find projects for customer ‘Acme Corp’”

“Show me all completed projects with tag ‘Q4-2025’”

Parameters:

• query (optional): Text search across project attributes
• uIDs (optional): Specific project IDs to retrieve
• dateFrom (optional): Filter by creation date (start)
• dateTo (optional): Filter by creation date (end)
• states (optional): Filter by project state (ACTIVE, ON_HOLD, COMPLETED, ARCHIVED)
• metaData (optional): Filter by metadata key-value pairs
• limit (optional): Maximum results (default 100, max 1000)

---

Get Project

Retrieves complete details for a specific project including owners, assets, tasks, and reference documents.

Sample prompts:

“Show me the details of project XYZ123”

“What assets are in the Packaging Redesign project?”

“Who are the owners of project ABC456?”

“What tasks are pending in the Q4 Campaign project?”

Parameters:

• uid (required): Unique project identifier

---

Create Project

Creates a new project with specified attributes.

Sample prompts:

"Create a new project called ‘Spring Campaign 2026’

“Start a project for customer Acme Corp, design name ‘Product Label Refresh’”

“Create a project with tags ‘urgent’ and ‘packaging’ due March 15th”

Parameters:

• name (required): Project name
• customer (optional): Customer name
• project (optional): Design project name
• design (optional): Design name
• revision (optional): Revision identifier
• description (optional): Project description
• tags (optional): Array of tags
• metaData (optional): Key-value pairs for custom metadata
• dueDate (optional): Completion due date

---

Update Project

Updates properties of an existing project.

Sample prompts:

“Update the project XYZ123 description to ‘Updated packaging requirements’”

“Change the due date for project ABC to March 30th”

“Add tag ‘priority’ to the Spring Campaign project”

“Update customer name to ‘Acme Corporation’ for project DEF789”

Parameters:

• uid (required): Project identifier
• All project attributes are optional; only provided fields are updated

---

Project State

Changes a project’s workflow state.

Sample prompts:

“Mark project XYZ123 as completed”

“Put the Spring Campaign project on hold”

“Archive the Q3 project”

“Reactivate the archived Packaging project”

Parameters:

• uid (required): Project identifier
• state (required): ACTIVE, ON_HOLD, COMPLETED, or ARCHIVED

---

Asset Management

Get Asset

Retrieves detailed information about a specific asset including version, status, and review statistics.

Sample prompts:

“Show me details for asset ABC123”

“What’s the status of the logo file?”

“Get the review status for asset XYZ789”

“Show me the thumbnail URL for the packaging asset”

Parameters:

• uid (required): Asset identifier

---

Upload Asset

Uploads a new asset file from an URL to a project.

Sample prompts:

“Upload the PDF from https://example.com/design.pdf to project XYZ”
“Add a new asset to the Packaging project from this URL”
“Upload logo.png to the active campaign project”

Parameters:

• projectUID (required): Target project identifier
• url (required): URL of the asset file to upload
• fileName (optional): Custom filename (defaults to URL filename)

Note: Asset processing is asynchronous. The asset will have status PENDING initially, then PROCESSED when ready or FAILED if processing fails.

---

Delete Asset

Permanently deletes an asset and reclaims storage space.

Sample prompts:

“Delete asset ABC123”

“Remove the outdated logo file from the project”

“Delete version 2 of the packaging design”

Parameters:

• assetUID (required): Asset identifier

---

Task Management

Get Task

Retrieves details about a specific task.

Sample prompts:

“Show me task(s) details for TASK123”
“What’s the status of the review task?”
“Who is assigned to task XYZ456?”

Parameters:

• uid (required): Task identifier

---

Create Upload Asset Task

Creates a task assigning a user to upload assets to a project.

Sample prompts:

“Ask John to upload assets to the Spring Campaign project”

“Create an upload task for [email protected] with due date next Friday”

“Assign an asset upload task to [email protected] for project ABC123”

Parameters:

• projectUID (required): Target project
• userUID (required): User to assign the task to
• dueDate (optional): Task deadline
• comment (optional): Instructions or notes

---

Create Upload Reference Document Task

Creates a task assigning a user to upload reference documents.

Sample prompts:

“Ask Sarah to upload the brand guidelines to the project”

“Create a reference document upload task for [email protected]”

“Assign a task to upload requirements to project XYZ”

Parameters:

• projectUID (required): Target project
• userUID (required): User to assign
• dueDate (optional): Deadline
• comment (optional): Instructions

---

Create Review Asset Task

Creates a task assigning an internal user to review and approve/reject assets.

Sample prompts:

“Ask the design director to review the new logo”

“Create a review task for [email protected] for assets ABC and XYZ”

“Assign the packaging assets to John for approval by next Monday”

Parameters:

• projectUID (required): Project containing the assets
• userUID (required): Internal user to review
• assetsUIDs (required): Array of asset identifiers to review
• dueDate (optional): Review deadline
• comment (optional): Review instructions

---

Create External Review Task

Creates a review task for an external user (identified by email).

Sample prompts:

“Send the logo to [email protected] for approval”

“Create an external review task for the packaging design”

“Ask external [email protected] to review assets ABC and DEF with password ‘secure123’”

Parameters:

• projectUID (required): Project identifier
• email (required): External reviewer’s email
• assetsUIDs (required): Assets to review
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Custom email subject
• password (optional): Password protection
• isAllowDownloadAssets (optional): Allow file downloads
• isReadOnly (optional): Prevent annotations

---

Create External Upload Asset Task

Creates a task for an external user to upload assets.

Sample prompts:

“Ask [email protected] to upload their logo to the project”

“Create an external upload task for [email protected]”

“Let external designer upload files to project ABC”

Parameters:

• projectUID (required): Target project
• email (required): External user’s email
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Email subject
• password (optional): Access password

---

Create External Upload Reference Document Task

Creates a task for an external user to upload reference documents.

Sample prompts:

“Ask the client to upload requirements to project XYZ”

“Create a task for [email protected] to upload specifications”

Parameters:

• projectUID (required): Target project
• email (required): External user’s email
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Email subject
• password (optional): Access password

---

Approve Task

Approves assets associated with a review task.

Sample prompts:

“Approve the review task TASK123”
“Accept the assets in the current review”
“Mark the logo review as approved”

Parameters:

• taskUID (required): Task identifier

---

Reject Task

Rejects assets associated with a review task.

Sample prompts:

“Reject task TASK456”

“Decline the packaging design review”

“Mark the review as rejected”

Parameters:

• taskUID (required): Task identifier

---

Complete Task

Marks a task as completed.

Sample prompts:

“Complete the upload task TASK789”

“Mark the reference document task as done”

“Close task ABC123”

Parameters:

• taskUID (required): Task identifier

---

Delete Task

Deletes a task (marks as deleted, won’t appear in UI).

Sample prompts:

“Delete the outdated review task”

“Remove task TASK999 from the project”

“Cancel the upload task”

Parameters:

• taskUID (required): Task identifier

---

Reference Document Management

Get Reference Document

Retrieves information about a specific reference document.

Sample prompts:

“Show me details for reference document DOC123”

“What’s the file size of the requirements document?”

“Get the download URL for the brand guidelines”

Parameters:

• uid (required): Reference document identifier

---

Upload Reference Document

Uploads a reference document from a URL to a project.

Sample prompts:

“Upload the requirements PDF to project XYZ”

“Add brand guidelines from https://example.com/guidelines.pdf as a reference document”

“Upload specifications to the Packaging project”

Parameters:

• projectUID (required): Target project
• url (required): Document URL
• fileName (optional): Custom filename

---

Add Reference Document URL

Adds a URL reference (no file download) to a project.

Sample prompts:

“Add a reference link to https://brand.example.com to the project”

“Link the online style guide to project ABC”

“Add URL reference for the external documentation”

Parameters:

• projectUID (required): Target project
• url (required): Reference URL

---

approval_studio_delete_refdoc

Deletes a reference document.

Sample prompts:

“Delete the outdated requirements document”

“Remove reference document DOC456”

“Delete the old brand guidelines”

Parameters:

• refDocUID (required): Document identifier

---

User Management

Get User

Retrieves information about a specific user.

Sample prompts:

“Show me details for user USER123”

“What email does John Smith use?”

“Get information about [email protected]”

Parameters:

• uid (required): User identifier

---

List Users

Lists all active users in the system.

Sample prompts:

“Show me all users in Approval Studio”

“List everyone on the team”

“Who are all the active users?”

Parameters: None

---

Webhook Management

Note: be careful with the webhook management over MCP prompts, as

List Webhooks

Lists registered webhooks.

Sample prompts:

“Show me all configured webhooks”

“List webhook endpoints”

“What webhooks are active?”

Parameters:

• uID (optional): Specific webhook identifier

---

Create Webhook

Registers a new webhook for event notifications.

Sample prompts:

“Create a webhook for project creation events at https://api.example.com/webhook”

“Register a webhook to notify when assets are uploaded”

“Set up a webhook for all task events”

Parameters:

• uRL (required): Webhook endpoint URL
• eventType (required): Event type to trigger on (PROJECT_CREATED, ASSET_UPLOADED, TASK_COMPLETED, ALL, etc.)

---

Delete Webhook

Deletes a webhook registration.

Sample prompts:

“Delete webhook WEBHOOK123”

“Remove the project creation webhook”

“Unregister the webhook at https://api.example.com/webhook”

Parameters:

• uID (required): Webhook identifier

---

Activity Timeline

List Timelines

Retrieves activity log entries with optional filtering.

Sample prompts:

“Show me recent activity in the system”

“List all events for project XYZ from last week”

“What happened in the Spring Campaign project yesterday?”

“Show me asset upload events from the past month”

Parameters:

• query (optional): Search text in event descriptions
• dateFrom (optional): Filter by event date (start)
• dateTo (optional): Filter by event date (end)
• projectUIDs (optional): Filter by specific projects
• limit (optional): Maximum results (default 100, max 1000)

---

Common Workflows

Creating a Complete Review Workflow

Sample conversation:

User: "Set up a new packaging project for Acme Corp"

AI: Creates project, returns project UID

User: "Upload the design from https://files.example.com/package.pdf"

AI: Uploads asset to the project

User: "Ask [email protected] to review it by Friday"

AI: Creates internal review task with due date

User: "Also send it to [email protected] for approval, password-protect it with 'acme2026'"

AI: Creates external review task with password

Checking Project Status

Sample conversation:

User: "What's the status of the Spring Campaign project?"

AI: Retrieves project details showing:
- 5 assets (3 processed, 2 pending)
- 2 active review tasks
- 1 completed upload task
- Review status: 60% approved

Managing Asset Versions

Sample conversation:

User: "Show me all versions of logo.png in project ABC"

AI: Queries project assets, filters by name "logo.png", shows versions 1-4

User: "Delete version 2, it's outdated"

AI: Deletes the specified asset version

---

Error Handling

The MCP server handles common errors gracefully:

• Authentication errors: Prompts for credentials if token is expired or invalid.
• Not found errors: Clearly indicates when projects, assets, or tasks don’t exist.
• Validation errors: Explains missing required fields or invalid parameters.
• Processing errors: Provides status updates for asynchronous operations like asset uploads.

---

Best Practices

1. Asset Uploads: Always check asset status after uploading, as processing is asynchronous.
2. External Tasks: Use clear comments and appropriate email subjects for external reviewers.
3. Project Organization: Use tags and metadata consistently for easier filtering.
4. Task Management: Set realistic due dates and provide clear instructions in comments.
5. Webhooks: Use specific event types rather than ALL to reduce unnecessary notifications.

---

Data Types Reference

Project States

• ACTIVE: Project is active and editable
• ON_HOLD: Paused but still accessible
• COMPLETED: Finished, no active tasks allowed
• ARCHIVED: Moved to archive, minimal activity
• IN_TRANSIT: Temporary state during transitions

Asset Status

• PENDING: Currently processing
• PROCESSED: Ready for use
• FAILED: Processing failed

Task Types

• UPLOAD_ASSETS: Internal asset upload
• UPLOAD_REF_DOCS: Internal reference doc upload
• REVIEW_ASSETS: Internal asset review
• EXTERNAL_REVIEW_ASSETS: External asset review
• EXTERNAL_UPLOAD_ASSET: External asset upload
• EXTERNAL_UPLOAD_REFDOC: External doc upload

Task Status

• PENDING: Active, awaiting completion
• CLOSED: Completed
• APPROVED: Review approved
• REJECTED: Review rejected
• APPROVED_WITH_CHANGES: Conditionally approved

Webhook Event Types

• PROJECT_CREATED, PROJECT_EDITED, PROJECT_STATE
• ASSET_UPLOADED, ASSET_DELETED
• REF_DOC_UPLOADED, REF_DOC_DELETED
• ANNOTATION_ADDED, ANNOTATION_EDITED, ANNOTATION_DELETED
• TASK_CREATED, TASK_COMPLETED, TASK_DELETED, TASK_APPROVED, TASK_REJECTED
• ALL: Triggers on any event

---

Limitations

• File Uploads: Direct file uploads not supported; must upload from accessible URLs.
• Rate Limits: Respect Approval Studio’s API rate limits.
• File Types: Only specific formats supported for assets (PDF, images, documents, video).
• Query Limits: Maximum 1000 results per query.

---

Support

For issues with the Approval Studio platform itself, consult:

• Online API Reference: https://approval.studio/api/graphql-view-documentation
• PDF Documentation: https://approval.studio/api/graphql-download-documentation
• Support Portal: https://approvalstudio.freshdesk.com/

Introduction

Model Context Protocol (MCP) is a standardized framework developed by Anthropic; it enables AI models to seamlessly connect with external tools and data sources without requiring custom integrations for each platform. By serving as a universal protocol, MCP ensures that AI applications can access real-time, contextually relevant data in a secure, scalable and efficient way.

From practical point of view, MCP is a (network) service you may connect to to be able to work using an AI model with an external or local resource; in this case this resource is Approval Studio.

You connect the MCP and manage Approval Studio, querying data and make changes.

For example, you may ask "Find me projects created in May 2025 and enumerate all the assets in them" or "Create a new project, name it 'Flyer for school' and create an upload task assigned on [email protected]".

You may also ask AI to help in understanding Approval Studio concepts, troubleshooting etc like you do asking a customer service person.

The MCP is build around the Approval Studio’s GraphQL API, so please refer the documentation to see what exactly you can do with the system using MCP.

Getting Started

Before using the MCP, you must authenticate with your Approval Studio credentials. The server handles token management automatically, but you’ll need to provide your credentials.

Approval Studio MCP uses bearer token to authenticate.

Every AI client, like Claude, that allows to configure external MCP, should be provided with the bearer token.

For Claude Windows/Mac the configuration looks like this:

{
  "mcpServers": {
		"ApprovalStudio": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://mcp.approval.studio",
			    "--header",
        		"Authorization:${AUTH_HEADER}"			
			],
			"env": {
				"AUTH_HEADER": "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
			}
		}
	}
}

You may find it in Settings->Developer->Local MCP servers->Edit Config

The bearer token is the same you use in REST API or GraphQL API so you may user one of the to generate token.

So having the auth token provided, MCP will interact with the system using the user account provided in the token, and, therefore, all the MCP activities you may see in the timeline or proof report will as activities of the authenticated user.

Core Concepts

Having MCP connected, you can use natural language interacting with Model by asking questions related to general principles, like asking a support people, querying data, statistics, and making changes.

Sample prompts:

Show me 10 most recent created projects.

What new assets were uploaded to the system for the last 3 days?

What assets were approved and rejected since last Friday?

Are there any active projects that are stuck? (no updates for the last couple of dates).

Create a new project, name it “Magazine cover design” and upload an asset from URL “https://address.com/design.pdf”

Find a project “Magazine cover design”, take the assets and requirements from the reference docs and create a detailed report how the assets follows the requirements.

Note: Working with files might be tricking due possible restrictions of the model or client. Generally accepted restriction is 1Mb, but can vary depends of the model and client. This MCP compresses images downloaded from the Approval Studio to fit in this limit (only .jpeg and .png).

Additionally, workflow engines like Zapier or n8n provide additional security restrictions and, usually, refuse to load files from any external sources.

If you use MCP to build a flow there you need to deal with the restrictions by uploading files to some internal storage or smth like this.

Available Tools

Approval Studio organizes work around these key entities:

Projects	Container for all design work, assets, tasks, and documents.
Assets	Design files (PDF, images, videos) that need review and approval.
Tasks	Work assignments for uploading, reviewing, or approving assets.
Reference Documents	Supporting materials like requirements, standards, or examples.
Users	Team members who own projects or are assigned tasks.
Workflows	Automated approval processes.

Note: Many of the sample prompts require a context; for example a prompt Get the review status for asset XYZ789 requires that the project this asset belongs to is provided somewhere earlier, so that the model would know it.

Project Management

List Projects

Retrieves a list of projects with optional filtering by date range, state, metadata, or search query.

Sample prompts:

“Show me all my active Approval Studio projects”

“List projects created in the last week”

“Find projects for customer ‘Acme Corp’”

“Show me all completed projects with tag ‘Q4-2025’”

Parameters:

• query (optional): Text search across project attributes
• uIDs (optional): Specific project IDs to retrieve
• dateFrom (optional): Filter by creation date (start)
• dateTo (optional): Filter by creation date (end)
• states (optional): Filter by project state (ACTIVE, ON_HOLD, COMPLETED, ARCHIVED)
• metaData (optional): Filter by metadata key-value pairs
• limit (optional): Maximum results (default 100, max 1000)

---

Get Project

Retrieves complete details for a specific project including owners, assets, tasks, and reference documents.

Sample prompts:

“Show me the details of project XYZ123”

“What assets are in the Packaging Redesign project?”

“Who are the owners of project ABC456?”

“What tasks are pending in the Q4 Campaign project?”

Parameters:

• uid (required): Unique project identifier

---

Create Project

Creates a new project with specified attributes.

Sample prompts:

"Create a new project called ‘Spring Campaign 2026’

“Start a project for customer Acme Corp, design name ‘Product Label Refresh’”

“Create a project with tags ‘urgent’ and ‘packaging’ due March 15th”

Parameters:

• name (required): Project name
• customer (optional): Customer name
• project (optional): Design project name
• design (optional): Design name
• revision (optional): Revision identifier
• description (optional): Project description
• tags (optional): Array of tags
• metaData (optional): Key-value pairs for custom metadata
• dueDate (optional): Completion due date

---

Update Project

Updates properties of an existing project.

Sample prompts:

“Update the project XYZ123 description to ‘Updated packaging requirements’”

“Change the due date for project ABC to March 30th”

“Add tag ‘priority’ to the Spring Campaign project”

“Update customer name to ‘Acme Corporation’ for project DEF789”

Parameters:

• uid (required): Project identifier
• All project attributes are optional; only provided fields are updated

---

Project State

Changes a project’s workflow state.

Sample prompts:

“Mark project XYZ123 as completed”

“Put the Spring Campaign project on hold”

“Archive the Q3 project”

“Reactivate the archived Packaging project”

Parameters:

• uid (required): Project identifier
• state (required): ACTIVE, ON_HOLD, COMPLETED, or ARCHIVED

---

Asset Management

Get Asset

Retrieves detailed information about a specific asset including version, status, and review statistics.

Sample prompts:

“Show me details for asset ABC123”

“What’s the status of the logo file?”

“Get the review status for asset XYZ789”

“Show me the thumbnail URL for the packaging asset”

Parameters:

• uid (required): Asset identifier

---

Upload Asset

Uploads a new asset file from an URL to a project.

Sample prompts:

“Upload the PDF from https://example.com/design.pdf to project XYZ”
“Add a new asset to the Packaging project from this URL”
“Upload logo.png to the active campaign project”

Parameters:

• projectUID (required): Target project identifier
• url (required): URL of the asset file to upload
• fileName (optional): Custom filename (defaults to URL filename)

Note: Asset processing is asynchronous. The asset will have status PENDING initially, then PROCESSED when ready or FAILED if processing fails.

---

Delete Asset

Permanently deletes an asset and reclaims storage space.

Sample prompts:

“Delete asset ABC123”

“Remove the outdated logo file from the project”

“Delete version 2 of the packaging design”

Parameters:

• assetUID (required): Asset identifier

---

Task Management

Get Task

Retrieves details about a specific task.

Sample prompts:

“Show me task(s) details for TASK123”
“What’s the status of the review task?”
“Who is assigned to task XYZ456?”

Parameters:

• uid (required): Task identifier

---

Create Upload Asset Task

Creates a task assigning a user to upload assets to a project.

Sample prompts:

“Ask John to upload assets to the Spring Campaign project”

“Create an upload task for [email protected] with due date next Friday”

“Assign an asset upload task to [email protected] for project ABC123”

Parameters:

• projectUID (required): Target project
• userUID (required): User to assign the task to
• dueDate (optional): Task deadline
• comment (optional): Instructions or notes

---

Create Upload Reference Document Task

Creates a task assigning a user to upload reference documents.

Sample prompts:

“Ask Sarah to upload the brand guidelines to the project”

“Create a reference document upload task for [email protected]”

“Assign a task to upload requirements to project XYZ”

Parameters:

• projectUID (required): Target project
• userUID (required): User to assign
• dueDate (optional): Deadline
• comment (optional): Instructions

---

Create Review Asset Task

Creates a task assigning an internal user to review and approve/reject assets.

Sample prompts:

“Ask the design director to review the new logo”

“Create a review task for [email protected] for assets ABC and XYZ”

“Assign the packaging assets to John for approval by next Monday”

Parameters:

• projectUID (required): Project containing the assets
• userUID (required): Internal user to review
• assetsUIDs (required): Array of asset identifiers to review
• dueDate (optional): Review deadline
• comment (optional): Review instructions

---

Create External Review Task

Creates a review task for an external user (identified by email).

Sample prompts:

“Send the logo to [email protected] for approval”

“Create an external review task for the packaging design”

“Ask external [email protected] to review assets ABC and DEF with password ‘secure123’”

Parameters:

• projectUID (required): Project identifier
• email (required): External reviewer’s email
• assetsUIDs (required): Assets to review
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Custom email subject
• password (optional): Password protection
• isAllowDownloadAssets (optional): Allow file downloads
• isReadOnly (optional): Prevent annotations

---

Create External Upload Asset Task

Creates a task for an external user to upload assets.

Sample prompts:

“Ask [email protected] to upload their logo to the project”

“Create an external upload task for [email protected]”

“Let external designer upload files to project ABC”

Parameters:

• projectUID (required): Target project
• email (required): External user’s email
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Email subject
• password (optional): Access password

---

Create External Upload Reference Document Task

Creates a task for an external user to upload reference documents.

Sample prompts:

“Ask the client to upload requirements to project XYZ”

“Create a task for [email protected] to upload specifications”

Parameters:

• projectUID (required): Target project
• email (required): External user’s email
• dueDate (optional): Deadline
• comment (optional): Instructions
• emailSubject (optional): Email subject
• password (optional): Access password

---

Approve Task

Approves assets associated with a review task.

Sample prompts:

“Approve the review task TASK123”
“Accept the assets in the current review”
“Mark the logo review as approved”

Parameters:

• taskUID (required): Task identifier

---

Reject Task

Rejects assets associated with a review task.

Sample prompts:

“Reject task TASK456”

“Decline the packaging design review”

“Mark the review as rejected”

Parameters:

• taskUID (required): Task identifier

---

Complete Task

Marks a task as completed.

Sample prompts:

“Complete the upload task TASK789”

“Mark the reference document task as done”

“Close task ABC123”

Parameters:

• taskUID (required): Task identifier

---

Delete Task

Deletes a task (marks as deleted, won’t appear in UI).

Sample prompts:

“Delete the outdated review task”

“Remove task TASK999 from the project”

“Cancel the upload task”

Parameters:

• taskUID (required): Task identifier

---

Reference Document Management

Get Reference Document

Retrieves information about a specific reference document.

Sample prompts:

“Show me details for reference document DOC123”

“What’s the file size of the requirements document?”

“Get the download URL for the brand guidelines”

Parameters:

• uid (required): Reference document identifier

---

Upload Reference Document

Uploads a reference document from a URL to a project.

Sample prompts:

“Upload the requirements PDF to project XYZ”

“Add brand guidelines from https://example.com/guidelines.pdf as a reference document”

“Upload specifications to the Packaging project”

Parameters:

• projectUID (required): Target project
• url (required): Document URL
• fileName (optional): Custom filename

---

Add Reference Document URL

Adds a URL reference (no file download) to a project.

Sample prompts:

“Add a reference link to https://brand.example.com to the project”

“Link the online style guide to project ABC”

“Add URL reference for the external documentation”

Parameters:

• projectUID (required): Target project
• url (required): Reference URL

---

approval_studio_delete_refdoc

Deletes a reference document.

Sample prompts:

“Delete the outdated requirements document”

“Remove reference document DOC456”

“Delete the old brand guidelines”

Parameters:

• refDocUID (required): Document identifier

---

User Management

Get User

Retrieves information about a specific user.

Sample prompts:

“Show me details for user USER123”

“What email does John Smith use?”

“Get information about [email protected]”

Parameters:

• uid (required): User identifier

---

List Users

Lists all active users in the system.

Sample prompts:

“Show me all users in Approval Studio”

“List everyone on the team”

“Who are all the active users?”

Parameters: None

---

Webhook Management

Note: be careful with the webhook management over MCP prompts, as

List Webhooks

Lists registered webhooks.

Sample prompts:

“Show me all configured webhooks”

“List webhook endpoints”

“What webhooks are active?”

Parameters:

• uID (optional): Specific webhook identifier

---

Create Webhook

Registers a new webhook for event notifications.

Sample prompts:

“Create a webhook for project creation events at https://api.example.com/webhook”

“Register a webhook to notify when assets are uploaded”

“Set up a webhook for all task events”

Parameters:

• uRL (required): Webhook endpoint URL
• eventType (required): Event type to trigger on (PROJECT_CREATED, ASSET_UPLOADED, TASK_COMPLETED, ALL, etc.)

---

Delete Webhook

Deletes a webhook registration.

Sample prompts:

“Delete webhook WEBHOOK123”

“Remove the project creation webhook”

“Unregister the webhook at https://api.example.com/webhook”

Parameters:

• uID (required): Webhook identifier

---

Activity Timeline

List Timelines

Retrieves activity log entries with optional filtering.

Sample prompts:

“Show me recent activity in the system”

“List all events for project XYZ from last week”

“What happened in the Spring Campaign project yesterday?”

“Show me asset upload events from the past month”

Parameters:

• query (optional): Search text in event descriptions
• dateFrom (optional): Filter by event date (start)
• dateTo (optional): Filter by event date (end)
• projectUIDs (optional): Filter by specific projects
• limit (optional): Maximum results (default 100, max 1000)

---

Common Workflows

Creating a Complete Review Workflow

Sample conversation:

User: "Set up a new packaging project for Acme Corp"

AI: Creates project, returns project UID

User: "Upload the design from https://files.example.com/package.pdf"

AI: Uploads asset to the project

User: "Ask [email protected] to review it by Friday"

AI: Creates internal review task with due date

User: "Also send it to [email protected] for approval, password-protect it with 'acme2026'"

AI: Creates external review task with password

Checking Project Status

Sample conversation:

User: "What's the status of the Spring Campaign project?"

AI: Retrieves project details showing:
- 5 assets (3 processed, 2 pending)
- 2 active review tasks
- 1 completed upload task
- Review status: 60% approved

Managing Asset Versions

Sample conversation:

User: "Show me all versions of logo.png in project ABC"

AI: Queries project assets, filters by name "logo.png", shows versions 1-4

User: "Delete version 2, it's outdated"

AI: Deletes the specified asset version

---

Error Handling

The MCP server handles common errors gracefully:

• Authentication errors: Prompts for credentials if token is expired or invalid.
• Not found errors: Clearly indicates when projects, assets, or tasks don’t exist.
• Validation errors: Explains missing required fields or invalid parameters.
• Processing errors: Provides status updates for asynchronous operations like asset uploads.

---

Best Practices

1. Asset Uploads: Always check asset status after uploading, as processing is asynchronous.
2. External Tasks: Use clear comments and appropriate email subjects for external reviewers.
3. Project Organization: Use tags and metadata consistently for easier filtering.
4. Task Management: Set realistic due dates and provide clear instructions in comments.
5. Webhooks: Use specific event types rather than ALL to reduce unnecessary notifications.

---

Data Types Reference

Project States

• ACTIVE: Project is active and editable
• ON_HOLD: Paused but still accessible
• COMPLETED: Finished, no active tasks allowed
• ARCHIVED: Moved to archive, minimal activity
• IN_TRANSIT: Temporary state during transitions

Asset Status

• PENDING: Currently processing
• PROCESSED: Ready for use
• FAILED: Processing failed

Task Types

• UPLOAD_ASSETS: Internal asset upload
• UPLOAD_REF_DOCS: Internal reference doc upload
• REVIEW_ASSETS: Internal asset review
• EXTERNAL_REVIEW_ASSETS: External asset review
• EXTERNAL_UPLOAD_ASSET: External asset upload
• EXTERNAL_UPLOAD_REFDOC: External doc upload

Task Status

• PENDING: Active, awaiting completion
• CLOSED: Completed
• APPROVED: Review approved
• REJECTED: Review rejected
• APPROVED_WITH_CHANGES: Conditionally approved

Webhook Event Types

• PROJECT_CREATED, PROJECT_EDITED, PROJECT_STATE
• ASSET_UPLOADED, ASSET_DELETED
• REF_DOC_UPLOADED, REF_DOC_DELETED
• ANNOTATION_ADDED, ANNOTATION_EDITED, ANNOTATION_DELETED
• TASK_CREATED, TASK_COMPLETED, TASK_DELETED, TASK_APPROVED, TASK_REJECTED
• ALL: Triggers on any event

---

Limitations

• File Uploads: Direct file uploads not supported; must upload from accessible URLs.
• Rate Limits: Respect Approval Studio’s API rate limits.
• File Types: Only specific formats supported for assets (PDF, images, documents, video).
• Query Limits: Maximum 1000 results per query.

---

Support

For issues with the Approval Studio platform itself, consult:

• Online API Reference: https://approval.studio/api/graphql-view-documentation
• PDF Documentation: https://approval.studio/api/graphql-download-documentation
• Support Portal: https://approvalstudio.freshdesk.com/