MCP Integration (Model Context Protocol)

Connect Ascend to AI assistants like Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. Once connected, your AI assistant can read, search, and manage your Ascend workspace using natural language.

What Is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Ascend's MCP server exposes your workspace content — pages, databases, contacts, time entries, invoices, and more — so an AI assistant can interact with it directly.

Examples of what you can do:

"List all my databases" — browse your workspace
"Create a page called Meeting Notes with today's action items" — create content
"Show me all rows in the Clients database where Status is Active" — query data
"Log 2 hours of work on the Landing Page project" — track time
"Create an invoice for Acme Corp from last week's time entries" — generate invoices

Prerequisites

Before you begin

You'll need:

A Solo or Studio plan — MCP integration is not available on the Free plan
An Ascend API Token (see Public API guide for how to generate one)
Node.js 18+ installed on your machine
An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

No installation or repo checkout is required — the server is published to npm as optivation.io-ascend-mcp and your MCP client runs it on demand via npx.

Quick Start

1. Generate an API Token

Log in to Ascend and click your avatar → Settings
Navigate to API Keys in the sidebar
Click Create New Token, give it a name (e.g. Claude MCP)
Copy the key immediately — it won't be shown again

2. Configure Your MCP Client

Claude Desktop

Open your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Ascend MCP server:

json

{
  "mcpServers": {
    "ascend": {
      "command": "npx",
      "args": ["-y", "optivation.io-ascend-mcp"],
      "env": {
        "ASCEND_URL": "https://ascend.optivation.io",
        "ASCEND_API_TOKEN": "ascend_your_token_here"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP settings or project .mcp.json:

json

{
  "mcpServers": {
    "ascend": {
      "command": "npx",
      "args": ["-y", "optivation.io-ascend-mcp"],
      "env": {
        "ASCEND_URL": "https://ascend.optivation.io",
        "ASCEND_API_TOKEN": "ascend_your_token_here"
      }
    }
  }
}

3. Restart Your MCP Client

Restart Claude Desktop (or your MCP client) to pick up the new configuration. You should see "ascend" listed as a connected tool provider.

Configuration

The MCP server requires two environment variables:

Variable	Required	Description	Example
`ASCEND_URL`	Yes	Base URL of your Ascend instance	`https://ascend.optivation.io`
`ASCEND_API_TOKEN`	Yes	Your API token (starts with `ascend_`)	`ascend_abc123...`

Keep your token safe

Your API token has the same permissions as your user account. Never commit it to version control or share it publicly.

Available Tools

The MCP server exposes 69 tools across all major Ascend features. Each tool includes a risk classification — your AI assistant will see this context when deciding which tools to use.

Pages

Tool	Risk	Description
`list_pages`	Low	List pages in the workspace
`get_page`	Low	Read the full content of a page
`create_page`	Medium	Create a new page with title and content
`update_page`	Medium	Update a page's title or append content
`delete_page`	High	Permanently delete a page

Databases

Tool	Risk	Description
`list_databases`	Low	List databases with title and property summary
`get_database`	Low	Get database schema including all properties
`create_database`	Medium	Create a new database with properties
`update_database`	Medium	Rename a database or update its icon
`duplicate_database`	Medium	Duplicate a database schema (no rows)
`add_database_property`	Medium	Add a new typed property to a database

Database Rows

Tool	Risk	Description
`list_rows`	Low	List rows with optional filtering
`get_row`	Low	Get a single row with all property values
`create_row`	Medium	Create a new row with property values
`update_row`	Medium	Update property values on an existing row
`delete_row`	High	Permanently delete a row
`bulk_update_rows`	High	Update up to 200 rows matching a filter
`duplicate_row`	Medium	Duplicate an existing row
`attach_file_to_row`	Medium	Attach a file URL to a row property

Time Tracking

Tool	Risk	Description
`list_time_entries`	Low	List time entries, optionally filtered
`create_time_entry`	Medium	Log a manual time entry
`update_time_entry`	Medium	Update a time entry's duration or note
`delete_time_entry`	High	Delete a time entry
`get_time_summary`	Low	Get total hours, earnings, and count
`start_timer`	Medium	Start a live timer
`stop_timer`	Medium	Stop the running timer
`pause_timer`	Low	Pause the running timer

Contacts & Jobs

Tool	Risk	Description
`list_contacts`	Low	List contacts with name, email, organization
`get_contact`	Low	Get full contact details
`create_contact`	Medium	Create a new contact
`update_contact`	Medium	Update an existing contact
`list_jobs`	Low	List active jobs/services
`get_job`	Low	Get job details including rates
`create_job`	Medium	Create a new job with billing config
`update_job`	Medium	Update a job's name or rate

Invoicing

Tool	Risk	Description
`list_invoices`	Low	List invoices, filter by status
`get_invoice`	Low	Get full invoice details
`create_invoice`	Medium	Create a draft invoice from time entries
`update_invoice_status`	High	Change invoice status (draft/sent/paid/void)

Agent-created invoices are drafts

create_invoice creates a draft — it computes the total from the linked time entries (and marks them billed so the same hours can't be invoiced twice) and assigns a real sequential invoice number. Open the invoice in Ascend to review and finalize it before sending.

Workspaces, Views, Templates & More

Tool	Risk	Description
`list_workspaces`	Low	List team workspaces
`create_workspace`	Medium	Create a new workspace
`update_workspace`	Medium	Update workspace name, icon, or description
`list_views`	Low	List views for a database
`create_view`	Medium	Create a table, kanban, or calendar view
`update_view`	Medium	Update a view's name, type, or config
`list_templates`	Low	List reusable page templates
`create_template`	Medium	Create a reusable page template
`apply_template`	Medium	Create a new page from a template
`search_workspace`	Low	Full-text search across pages and rows
`list_tags`	Low	List all tags
`create_tag`	Low	Create a new tag
`tag_entity`	Low	Apply a tag to a page or row

Inbox & Alerts

Tool	Risk	Description
`list_inbox_items`	Low	List inbox notifications
`mark_inbox_item_read`	Low	Mark a notification as read
`dismiss_inbox_item`	Low	Dismiss a notification
`list_alerts`	Low	List system alerts
`acknowledge_alert`	Medium	Acknowledge an open alert
`resolve_alert`	Medium	Mark an alert as resolved
`create_alert_rule`	Medium	Create an SLA alert rule
`link_notification_to_entity`	Low	Link a notification to a page or row
`quick_create_from_inbox`	Medium	Create a page from a notification

Booking & Scheduling

Tool	Risk	Description
`booking.list_event_types`	Low	List booking event types (one-to-one, group, round-robin, etc.)
`booking.get_event_type`	Low	Get a single event type with its hosts and configuration
`booking.list_bookings`	Low	List bookings (defaults to upcoming)
`booking.get_booking`	Low	Get a single booking's details
`booking.get_availability`	Low	Get available slots for a published event type
`booking.create_booking`	High	Book a slot on an attendee's behalf (sends confirmations)
`booking.cancel_booking`	High	Cancel a booking (sends emails, refunds payment if applicable)
`booking.reschedule_booking`	High	Reschedule a booking to a new time

Resources

In addition to tools, the MCP server exposes Ascend content as browsable resources. Your AI assistant can read these to understand your workspace structure.

Resource URI	Description
`ascend://workspaces`	List all team workspaces
`ascend://workspace/{id}`	Workspace with its pages and databases
`ascend://page/{id}`	Full page content
`ascend://database/{id}`	Database schema and properties

Prompt Templates

The server includes pre-built prompts for common workflows:

Prompt	Arguments	Description
`summarize-page`	`pageId`	Fetches a page and asks for a summary
`analyze-database`	`databaseId`	Fetches schema + sample rows and asks for analysis
`workspace-overview`	`workspaceId`	Fetches workspace contents and asks for an overview

Running Manually

You can also run the MCP server directly from the terminal:

bash

ASCEND_URL=https://ascend.optivation.io ASCEND_API_TOKEN=ascend_... npx -y optivation.io-ascend-mcp

Testing with MCP Inspector

The MCP Inspector is an interactive tool for testing MCP servers:

bash

ASCEND_URL=https://ascend.optivation.io ASCEND_API_TOKEN=ascend_... \
  npx @modelcontextprotocol/inspector npx -y optivation.io-ascend-mcp

This opens a browser UI where you can:

Browse all registered tools and their schemas
Execute tools with custom parameters
Read resources
Test prompt templates

Risk Classifications

Each tool has a risk level that your AI assistant can see:

Level	Meaning	Examples
Low	Read-only operations, safe to run	`list_pages`, `get_database`, `search_workspace`
Medium	Creates or modifies data	`create_page`, `update_row`, `start_timer`
High	Destructive or irreversible operations	`delete_page`, `delete_row`, `bulk_update_rows`

INFO

High-risk tools are still available, but your AI assistant will typically ask for confirmation before executing them.

Troubleshooting

Problem	Solution
"Failed to connect to Ascend API"	Ensure Ascend is running at the URL in `ASCEND_URL`
"Unauthorized" (401)	Check your `ASCEND_API_TOKEN` is correct and not expired
"Team not found" (404)	Your token's user may not be a member of any team
"MCP integration requires Solo or Studio" (403)	Your team is on the Free plan — upgrade to Solo or Studio to use MCP
Tools not appearing in Claude	Restart Claude Desktop after changing config
MCP server exits immediately	Check stderr output for error details

Debug mode

Run the MCP server directly in your terminal to see error output:

bash

ASCEND_URL=https://ascend.optivation.io ASCEND_API_TOKEN=ascend_... npx -y optivation.io-ascend-mcp

All diagnostic messages are written to stderr.

Security

The MCP server authenticates with your personal API token
All requests go through Ascend's standard permission system
The server inherits your user's team membership and role
No data is stored locally — everything flows through the Ascend API
The MCP server runs as a local process on your machine

Related guides:

MCP Integration (Model Context Protocol) ​

What Is MCP? ​

Prerequisites ​

Quick Start ​

1. Generate an API Token ​

2. Configure Your MCP Client ​

Claude Desktop ​

Claude Code ​

3. Restart Your MCP Client ​

Configuration ​

Available Tools ​

Pages ​

Databases ​

Database Rows ​

Time Tracking ​

Contacts & Jobs ​

Invoicing ​

Workspaces, Views, Templates & More ​

Inbox & Alerts ​

Booking & Scheduling ​

Resources ​

Prompt Templates ​

Running Manually ​

Testing with MCP Inspector ​

Risk Classifications ​

Troubleshooting ​

Security ​

MCP Integration (Model Context Protocol)

What Is MCP?

Prerequisites

Quick Start

1. Generate an API Token

2. Configure Your MCP Client

Claude Desktop

Claude Code

3. Restart Your MCP Client

Configuration

Available Tools

Pages

Databases

Database Rows

Time Tracking

Contacts & Jobs

Invoicing

Workspaces, Views, Templates & More

Inbox & Alerts

Booking & Scheduling

Resources

Prompt Templates

Running Manually

Testing with MCP Inspector

Risk Classifications

Troubleshooting

Security