MCP Integration (Model Context Protocol)

Connect Ascend to AI assistants like Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. Once connected, your assistant can read, search, and manage your Ascend workspace in plain language — no copy-pasting between tabs.

What Is MCP?

The Model Context Protocol is an open standard, published by Anthropic, that lets AI assistants connect to external tools and data. Ascend's MCP server exposes your workspace — pages, databases, contacts, time entries, invoices, bookings — so an assistant can work with it directly.

Examples of what you can ask:

"What did I work on for Acme last week?" — read time entries
"Draft an invoice for Acme from March's unbilled hours" — generate invoices
"Add a note to the Acme project with today's action items" — create content
"Show me every row in Clients where Status is Active" — query databases
"What's on my calendar Thursday, and where are the gaps?" — check bookings

Prerequisites

Before you begin

Two things can stop you before you start:

A Solo or Studio plan. MCP is not available on Free — a Free-plan token is rejected before any tool runs.
An MCP-compatible client — Claude Desktop, Claude Code, Cursor, or anything else supporting the protocol.

You'll also need Node.js 18+ and an API token, both covered in the steps below.

Nothing to install or clone. The server is published to npm as @optivation/ascend-mcp, and your client downloads and runs it on demand via npx — it runs locally on your machine, not on a server you have to manage.

Installation

Setup is four steps and takes about five minutes. There is nothing to install first — your MCP client downloads the server on demand.

1. Check you have Node.js 18 or newer

bash

node --version

If that errors or shows a version below 18, install the LTS release from nodejs.org and reopen your terminal.

2. Generate an API token

Log in to Ascend and click your avatar → Settings
Go to API Keys in the sidebar
Click Create New Token and name it (e.g. Claude MCP)
Copy it immediately — it is shown once and never again

WARNING

Treat the token like a password. It carries the same permissions as your account, so anyone holding it can read and change your workspace. Never commit it or paste it into a shared document.

3. Add Ascend to your MCP client

Pick your client below. The configuration is the same shape in each — only the file location differs.

Claude Desktop

Open the config file, creating it if it doesn't exist:

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

json

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

If the file already has an mcpServers block, add "ascend" inside it rather than replacing what's there.

Claude Code

Create .mcp.json in your project root, or add to your global Claude Code MCP settings:

json

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

To keep the token out of a file you might commit, reference an environment variable instead — Claude Code expands ${VAR} at load time:

json

"ASCEND_API_TOKEN": "${ASCEND_API_TOKEN}"

Cursor

Open Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly:

json

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

Any other MCP client

Any client supporting the stdio transport works. Point it at the command npx -y @optivation/ascend-mcp and pass ASCEND_URL and ASCEND_API_TOKEN as environment variables.

4. Restart and confirm

Restart your client fully — reloading a window is usually not enough. ascend should then appear in its list of connected tool providers.

The first launch is slower than later ones, because npx downloads the package before running it.

To confirm the connection is genuinely working rather than just listed, ask your assistant:

List my Ascend workspaces

A correct answer means the token, the plan gate and the tool surface are all working. If it returns an error or nothing at all, see Troubleshooting.

Check it from a terminal instead

Running the server yourself shows exactly what your client sees, which is the fastest way to diagnose a failure:

bash

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

A healthy start prints:

Fetched 18 tool definitions from https://ascend.optivation.io
Team: Acme Consulting (id 3)
Registered all tools, resources, and prompts.
Ascend MCP server running on stdio.

It then waits for input, which is correct — press Ctrl+C to stop it.

Configuration

Two environment variables are required, and a third is optional.

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...`
`ASCEND_TEAM_ID`	No	Team to work in, if you belong to more than one	`3`

Keep your token safe

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

Working in a specific team

If your account belongs to more than one team, set ASCEND_TEAM_ID to choose which one the tools act on. Leave it unset and every call goes to your default team — which, for a multi-team account, is simply the first membership on record rather than the team you were last working in.

The server confirms the team it connected to at startup. If Ascend resolves a different team than you asked for — almost always because your user isn't a member of it — the server stops with an error instead of starting.

That refusal is deliberate. An unrecognised team ID falls back silently on the server side, so without the check you would get a perfectly working session pointed at the wrong workspace, where creating invoices and cancelling bookings all succeed against real data.

How the tools work

Ascend exposes 18 tools. Most areas of the product have one read_* tool and one write_* tool, and you choose the specific operation with an action parameter:

read_workspace   action: "databases"      → list your databases
write_time       action: "start_timer"    → start the live timer
write_invoices   action: "create"         → draft an invoice

You never type this yourself — your assistant fills it in. It matters only because it explains why there are 18 tools rather than one per operation.

Why 18 and not one tool per operation

Published benchmarks show AI tool-selection accuracy degrades noticeably past roughly 20 available tools, and collapses near 100 — at ~20 tools a large model picks correctly 19 times out of 20. Comparable products ship small surfaces for the same reason: Linear exposes 5 tools and Notion 13. Ascend previously exposed 69, and consolidating to 18 makes the assistant markedly more reliable at picking the right one.

Every tool also carries MCP annotations — readOnlyHint, destructiveHint, idempotentHint and openWorldHint — which tell your assistant whether an operation only reads data, can't be undone, or reaches outside Ascend (sending email, charging a card). Clients use these to decide when to ask you for confirmation.

Available tools

Reads — 9 tools

Safe to run. These never modify anything.

Tool	Actions	What it reads
`search`	`query`	Pages and database rows by text (use `read_workspace` action `databases` to find databases themselves)
`read_workspace`	`workspaces`, `databases`, `database`, `views`, `templates`	Workspaces, database schemas, views, templates
`read_rows`	`list`, `get`	Rows in a database, or one row's values
`read_pages`	`list`, `get`	Page list, or a page's full content
`read_clients`	`jobs`, `job`, `contacts`, `contact`	Jobs and contacts
`read_time`	`entries`, `summary`, `tags`	Time entries, hours and earnings summary, tags
`read_invoices`	`list`, `get`	Invoices, optionally filtered by status
`read_inbox`	`items`, `alerts`	Inbox notifications and system alerts
`read_bookings`	`event_types`, `event_type`, `bookings`, `booking`, `availability`	Event types, bookings, and open slots

Writes — 8 tools

Create and modify data. Your assistant will usually confirm the higher-risk ones first.

Tool	Risk	Actions	What it does
`write_workspace`	Medium	`create_workspace`, `update_workspace`, `create_database`, `update_database`, `duplicate_database`, `add_property`, `create_view`, `update_view`, `create_template`, `apply_template`	Build and edit workspaces, databases, views, templates
`write_rows`	High	`create`, `update`, `duplicate`, `bulk_update`, `attach_file`	Add or change rows, including bulk updates of up to 200
`write_pages`	Medium	`create`, `update`	Create a page, or change its title and content
`write_clients`	Medium	`create_job`, `update_job`, `create_contact`, `update_contact`	Create and update jobs and contacts
`write_time`	Medium	`create_entry`, `update_entry`, `start_timer`, `stop_timer`, `pause_timer`, `create_tag`, `tag_entity`	Log time, run the live timer, manage tags
`write_invoices`	High	`create`, `update_status`	Draft an invoice from time entries, or change its status
`write_inbox`	Medium	`mark_read`, `dismiss`, `link_entity`, `quick_create`, `acknowledge_alert`, `resolve_alert`, `create_alert_rule`	Manage notifications, alerts, and alert rules
`write_bookings`	High	`create`, `reschedule`, `cancel`	Book, reschedule or cancel — sends emails and issues refunds on cancel

Agent-created invoices are drafts

write_invoices with action: "create" produces a draft. It totals the linked time entries, marks them billed so the same hours can't be invoiced twice, and assigns a real sequential invoice number. Open it in Ascend to review and finalise before sending.

Deletion — 1 tool

Tool	Risk	Actions	What it does
`delete_item`	High	`row`, `page`, `time_entry`	Permanently deletes a row, page, or time entry

delete_item is flagged destructiveHint: true, so a well-behaved client will ask before running it. Deletion is permanent and cannot be undone from the assistant.

Resources

Beyond tools, the server exposes your content as browsable resources, which an assistant can read to understand how your workspace is laid out.

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

Prompt templates

The server ships pre-built prompts for common jobs:

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

Running it manually

You can start the server straight from a terminal, which is the quickest way to check a token:

bash

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

Testing with MCP Inspector

The MCP Inspector is an interactive UI for exercising an MCP server:

bash

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

It opens a browser where you can browse every registered tool and its schema, run tools with your own parameters, read resources, and try the prompt templates.

Risk levels

Every tool carries a risk classification your assistant can see.

Level	Meaning	Examples
Low	Read-only, safe to run	`search`, `read_pages`, `read_workspace`
Medium	Creates or changes data	`write_pages`, `write_time`, `write_clients`
High	Irreversible, or reaches outside Ascend	`delete_item`, `write_bookings`, `write_invoices`

INFO

High-risk tools remain available — your assistant will typically ask for confirmation before running one.

Troubleshooting

Problem	Solution
"Failed to connect to Ascend API"	Check Ascend is reachable at the URL in `ASCEND_URL`
"Unauthorized" (401)	Your `ASCEND_API_TOKEN` is wrong, revoked, or expired
"Team not found" (404)	The token's user isn't a member of any team
"MCP integration requires Solo or Studio" (403)	Your team is on the Free plan — upgrade to use MCP
"requested ASCEND_TEAM_ID=… but Ascend resolved team …"	Your user isn't a member of that team. Check the ID, or unset `ASCEND_TEAM_ID` to use your default
"ASCEND_TEAM_ID must be a positive integer"	Use the numeric team ID, not the team name
Tools acting on the wrong workspace	Set `ASCEND_TEAM_ID`, then check the `Team:` line printed at startup
Tools not appearing in Claude	Restart the client after changing its config
Server exits immediately	Run it manually (above) to see the error on stderr

Debug mode

Run the server directly in a terminal to see everything it reports:

bash

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

All diagnostics go to stderr, so they won't interfere with the protocol.

Security

Tokens are scoped to your account. The MCP server can do exactly what you can do, and nothing more.
Every request is authenticated and team-scoped. Tools cannot reach another team's data.
The plan gate is enforced on the server. A Free-plan token is rejected before any tool runs.
Nothing is stored locally. The server is a stateless proxy between your client and the Ascend API.
Revoke any time in Settings → API Keys; revocation takes effect immediately.

Public API — generate tokens and call Ascend over REST
Setting up integrations — connect email, calendar and other tools

MCP Integration (Model Context Protocol) ​

What Is MCP? ​

Prerequisites ​

Installation ​

1. Check you have Node.js 18 or newer ​

2. Generate an API token ​

3. Add Ascend to your MCP client ​

Claude Desktop ​

Claude Code ​

Cursor ​

Any other MCP client ​

4. Restart and confirm ​

Configuration ​

Working in a specific team ​

How the tools work ​

Available tools ​

Reads — 9 tools ​

Writes — 8 tools ​

Deletion — 1 tool ​

Resources ​

Prompt templates ​

Running it manually ​

Testing with MCP Inspector ​

Risk levels ​

Troubleshooting ​

Security ​

Related guides ​

Related

MCP Integration (Model Context Protocol)

What Is MCP?

Prerequisites

Installation

1. Check you have Node.js 18 or newer

2. Generate an API token

3. Add Ascend to your MCP client

Claude Desktop

Claude Code

Cursor

Any other MCP client

4. Restart and confirm

Configuration

Working in a specific team

How the tools work

Available tools

Reads — 9 tools

Writes — 8 tools

Deletion — 1 tool

Resources

Prompt templates

Running it manually

Testing with MCP Inspector

Risk levels

Troubleshooting

Security

Related guides