This article introduces the Ardoq MCP server and how it enables AI clients to retrieve real-time, structured data from Ardoq. It explains how the protocol works, what features Ardoq supports, and how to connect to Claude for Desktop, with connection guides to other clients coming soon.

What Is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how external tools and data sources can be exposed to large language models (LLMs). MCP acts as a universal adapter between models and tools, allowing AI clients to discover and use tools dynamically, with minimal manual integration.

For example, with MCP, an AI assistant can connect to a system like Ardoq and automatically access up-to-date information, such as lists of projects, reports, or applications. It can then use that context to answer questions, generate summaries, or assist with decision-making. This removes the need for manual copy-pasting or hardcoded API calls, making it easier to bring real-time business data into AI-powered workflows.

Tools and Features

The Ardoq MCP server provides AI assistants with secure, real-time access to your Ardoq data through a growing set of tools. For example, an assistant can list your available reports, run and summarize them, and generate charts or visualizations, all using natural language.

Below are a few examples of how an AI assistant connected to the Ardoq MCP server can interact with your data through natural language.

Example 1: Explore Available Reports
The assistant uses the get_reports tool to retrieve a complete list of reports from the Ardoq workspace.

Example 2: Generate a Detailed Report Summary
In this example, the assistant runs a selected report and returns a summary with key insights like cost, progress, and timelines.

Example 3: Generate a Visual Summary from Multiple BCM Reports
The assistant combines data from multiple business capability reports to generate a visual dashboard showing various metrics.

Ardoq’s MCP tools make it easy to access and work with your data and insights through natural language, without using the Ardoq UI. While current tools are read-only, upcoming support for write operations, human-in-the-loop workflows, and new features such as get_metamodel and populate_viewpoint will enable even more powerful use cases. To suggest additional tools, visit the Ardoq Product Portal via the feedback link in the app.

FAQ

Q: Which functionality is available via MCP?

A: Functionality will be added over time. The current functionality includes:

Reports: Get report definition, List reports, Execute Report
Current User: get the current user information
Ardoq Tip: get a tip on using ardoq

Q: How are permissions enforced?

A: The MCP server provides access to a subset of API functionality. The permission model is enforced by the API access. For example, the User (or Service User) of the API token will only be able to access reports for which they have permission to view in the tool.

Q: Do we need access to the Ardoq API to use MCP?

A: Yes. MCP is a gateway to API functionality. Access to the API is a prerequisite for use.

Q: What is the URL for the MCP server?

A: https://<your-host>.ardoq.com/mcp/ - Note the trailing '/'

Q: Why does my AI client not show the information I expect from the report?

A: AI clients make use of the MCP connection to fetch information from Ardoq based on the user request. The AI clients often interpret the results and provide a summary or inference of the returned data. This can sometimes result in presentation of text that is quite different to the data in the report.

Most AI MCP clients allow you to inspect the raw information sent and returned from MCP tools. Please check the raw information and not just the presented text.

Q: Why do I get an error message such as MaxTokenLengthExceeded? Is this a problem with the Ardoq MCP implementation?

A: These error messages are usually related to the configuration of the customer's AI MCP client. For example when the client does not have enough context window to process a lengthy Ardoq Report. The Ardoq MCP Server returns data to AI MCP clients in a similar way to system API calls. The setup of each particular AI MCP Client (e.g., ms-copilot studio) and its configuration (e.g., the quotas and limits for using AI) is specific to each customer.

We do test with a set of MCP clients and AI model providers but we cannot test for all combinations of clients and configurations.

We strongly suggest customers start by analysing a small report from Ardoq and then expand to larger reports based on AI context size that your AI provider allows.

Q: Which transport types does the Ardoq MCP server support?
A: Ardoq MCP supports the streamable http transport. There is no support for the deprecated sse transport protocol.

Q: Does Ardoq MCP server support python?
A: Yes, you can use the Ardoq MCP server with python or any programming/scripting language of your choice, given that it provides a library to connect with MCP servers. Below is an example python script of how to connect to the Ardoq MCP server using fastmcp.

import asyncio
import os
from pprint import pprint
from fastmcp import Client

# Connects to the Ardoq MCP server
# For this to work you need to
# - set the environment variable ARDOQ_API_TOKEN to your token
# - replace the your-org-label with your organization label below.

api_token = os.getenv("ARDOQ_API_TOKEN")
client = Client("https://your-org-label.ardoq.com/mcp/", auth=api_token)

async def main(): 
    async with client: 
    await client.ping() 

    tools = await client.list_tools() 

    print("Available tools:") 
    pprint(tools) 

    result = await client.call_tool("retrieve_current_user_and_verify_connection", {}) 
    print("Ardoq MCP tool result:") 
    pprint(result)

asyncio.run(main())

API Token Guidelines

To authenticate with the Ardoq MCP server, you must provide an API token in the Authorization header. This token should be generated from a service account, not tied to a personal user.

Follow these steps to create a secure and maintainable token for your integration:

1. Create a Service Account in Ardoq

In Ardoq, go to:
Preferences → Access Control → Service accounts
Click Create new
Fill in the required fields:
- Service account name – e.g., Claude MCP Access
- Token description – e.g., Used by Claude Desktop to access MCP server
- Service account role – Choose a role with the minimum permissions needed (e.g., read-only access to relevant workspaces)
Click Create service account
Copy and save the generated token securely. This token will be used in the MCP configuration.

You will not be able to view the token again after closing the dialog. Store it securely.

2. Manage Existing Service Accounts

To update or remove a token:

Click the three-dot menu next to the service account name
Select Regenerate token or Delete

Regenerating a token will break any existing integration using the old token.

3. Follow These Security Best Practices

Use service accounts exclusively for MCP integrations
Restrict access to only what’s needed for your use case
Keep the token secret – never hardcode it or commit it to version control. Use environment variables in your config

Using service accounts ensures better security, easier management, and avoids disruptions when team members leave your organization.

Connect an AI Assistant to the Ardoq MCP Server

There are multiple MCP clients that can connect to the Ardoq MCP server and use your own AI provider. Each platform has its own setup process, and we provide dedicated guides to help you get started with some of those. Choose your client below to view the installation and configuration instructions.

Claude Desktop

Requires a Claude Pro account to unlock full potential.

Microsoft Copilot Studio

Requires a Microsoft 365 Copilot or Copilot Studio license to use.

GitHub Copilot in VS Code

Requires access to GitHub Copilot.

5ire

Free open-source. Requires an AI assistant API key (such as Gemini).

Cherry

Free open-source. Requires an AI assistant API key (such as Gemini).

More guides will be added as additional platforms adopt MCP support. If there's a specific AI assistant platform you would like to see support for, you can suggest it by visiting the Ardoq Product Portal via the feedback link in the app.