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.
Prompt Guidance
Being successful using an external AI client with an architecture repository is highly dependent on the quality of the AI tool together with the expectations and skill of the person using it. We recommend following these principles:
Read and understand our guide on Context Engineering
Understand the strengths and weaknesses of LLMs. Treat your AI like a precocious, teenage apprentice and not as an architecture expert. Use it to fetch and summarize information for you to make the decisions.
Use smaller, specific requests rather than large analysis / decision questions.
Rather than asking "How much could we save if we decommissioned all the 'eliminate' applications?"
ask "which applications have been marked as 'Eliminate'?", "what is the cost of those applications marked as 'Eliminate'?".
Each specific request will result in the identification and extraction of a single report. Some AI's may be sophisticated enough to combine these steps in a reasoning chain. But not all of them are. So keep it simple to begin with.
Evaluate, evaluate, evaluate. Do not blindly trust the answers you get from AI. Test it until you know which useful prompts provide useful answers.
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.
Components: Search for component information. Optionally, specify the component type
Reports: List reports, get report definition, get report data. The tool for get report data also supports filtering.
Viewpoints: List viewpoints, get viewpoint definition, get viewpoint data.
Dashboards: List dashboards, get dashboard definition, get dashboard data
Metamodel: Get the organization metamodel
Additionally there are some utility functions that can be used by the AI client but which may not be relevant for end users
Resolve entity name: Resolve a human-readable name to an ID for any kind of entity (Component, Report, Dashboard, Viewpoint). This allows the ID to be used in other tool requests
Current User: get the current user information
Ardoq Support Guide: instructions to the AI client on how to use Ardoq MCP Server tools.
Ardoq Tip: get a tip on using ardoq (useful tool for testing the connection)
The MCP Server instructs the AI client to follow a chain of reasoning to select the correct tool and to follow suggests for follow-up actions in the returned results.
See the section on Ardoq Support Guide for how we instruct AI clients on how to use the tools and to follow a chain of reasoning.
Component Tools
Tool: search components
This tool can be used to search for specific components in Ardoq. The search will look for a case-insensitive substring in the name or description fields of components.
If a single component matches the search then a list of items is returned and the user can specify both a more specific name and the component type to retrieve the desired information
Report Tools
Tool: list reports
Request a list of reports in Ardoq. This can include a search qualifier that looks for words in the name or description of reports.
If the request results in a large list of tools then we may paginate the reports. The AI is instructed to inform the user that a subset of results is returned and they can request the next set of results. See the FAQ entry about pagination for more details.
Tool: get report
The user can get a specific report.
It is not necessary to request the list of reports beforehand. Nor is it necessary to be exact with the name. But doing so will help the AI to request the correct report.
The AI client is instructed to look for a report or dashboard if a user requests a summary of information from Ardoq rather than a specific component or architecture view. E.g., "which Applications are most at risk?" should result in a request for a report or dashboard that summarises application risk.
Requests for reports can also include filters. You can ask for a single filter based on a column value.
This tool returns the raw data, together with the column structure, for a report. How the AI client displays the results can vary. In the above screenshot the information is simply listed. You can ask your client to show the results in a tabular format to recreate the report structure
Note: the prompt to 'execute' a report. Asking to "get the report..." may result in executing the tool to get a report definitions. If that happens you should specify to 'execute' a report or to 'get the data' for a report.
Tool: get report definition
The user can request information about the structure of a report. For instance, to determine if it contains the desired information or to find details of columns that can be used for filtering the results in the report data.
This tool will often be called by the AI client, without user prompting, to identify if a report contains information that can match a user query.
Dashboard Tools
Tool: list dashboards
Request a list of dashboards in Ardoq. This can include a search qualifier that looks for words in the name or description of dashboards.
Pagination works the same as for the equivalent tool for Reports
Tool: get dashboard
Requesting a dashboard will return all the widgets with all their data from that dashboard. If the size of the data is too large then it will paginate the widgets returned.
Its also possible to requests individual widgets
Tool: get dashboard definition
The user can request information about the structure of a dashboard. For instance, to determine if it contains the desired information or to find details about the chart the dashboard contains.
This tool will often be called by the AI client, without user prompting, to identify if a dashboard contains information that can match a user query.
Viewpoint Tools
Tool: list viewpoints
Request a list of viewpoints in Ardoq. This can include a search qualifier that looks for words in the name or description of reports.
If the request results in a large list of items then we may paginate the results. The AI is instructed to inform the user that a subset of results is returned and they can request the next set of results. See the FAQ entry about pagination for more details.
Tool: get viewpoint or get view
The user can get a specific viewpoint.
It is not necessary to request the list of viewpoints beforehand. Nor is it necessary to be exact with the name. But doing so will help the AI to request the correct viewpoint.
The AI client is instructed to use this tool if it is prompted to look for a specific item together with an unknown item. For example, if the user prompts, "who is the owner of Customer Payments", it will attempt to find a viewpoint that begins with an application (assuming Customer Payments is an Application) that is connected with an owns reference to a Person type.
Note: sometimes a request will require confirmation. See the relevant FAQ answer below.
Tool: get viewpoint definition
The user can request information about the structure of a viewpoint. For instance, to determine if it contains the desired information or to find details of connections between component types.
This tool will often be called by the AI client, without user prompting, to identify if a viewpoints contains information that can match a user query.
Metamodel Tools
Tool: get metamodel
A user can request information about which information is available in Ardoq or how it is connected to other information. That will result in the metamodel tool being called to show the possible connections between component and reference types in your Ardoq instance.
Utility Tools
Some tools are provided to help check connections to the MCP Server and to help the AI client to call the previously documented tools. These are not intended to be requested directly by the end user but they are documented here because they can be useful for resolving issues.
Tool: resolve entity name
A tool to resolve a human-readable name to an ID for any kind of entity (Component, Report, Dashboard, or Viewpoint).
This is primarily to allow the AI client to find the ID of an item which is needed to call a tool. For example the get_report_data tool requires a unique report ID but humans refer to reports by name. When the user asks for a particular report, the AI client will first resolve the name to an ID and then use the ID to call the tool to get the report data.
This tool may be useful for end users to help resolve problems. For example, if the AI client is unsuccessful in returning a requested report. Then the user can ask, "resolve the name <insert report name>" and the tool will return the ID. The user can then follow up with "get the report with ID <insert ID>". This will help determine if the problem is with the AI client or the report in Ardoq.
Tool: get current user
The user can ask, "who am I in Ardoq?" and the tool will call the me endpoint in Ardoq public API.
This will show the current user in Ardoq that is associated with the API token being for MCP access. For instance, the Service User in the example below.
This can be useful to simply test the connection with Ardoq but also to identify the user when ensuring access control to information through the MCP Server.
Tool: Ardoq Tip
This is another helper function to test the connection with Ardoq. The prompt, "give me a tip about Ardoq", will return some static text about Ardoq features. This tool can be successfully called without an authentication token. This allows you to test you have a connection with Ardoq regardless of issues that may occur with access tokens.
Tool: Ardoq Support Guide
This tool returns simple example prompts you may wish to try when using the MCP Server. But its purpose is to contain sophisticated instructions on how the AI client should successfully turn a user prompt into correct Ardoq tool usage.
We wont detail how that happens in this article, but users who understand MCP can see how it works in the tool documentation.
FAQ
Q: Which functionality is available via MCP?
A: Functionality will be added over time. The current functionality includes:
Components: Search for component information. Optionally, specify the component type
Reports: List reports, get report definition, get report data
Viewpoints: List viewpoints, get viewpoint definition, get viewpoint data
Dashboards: List dashboards, get dashboard definition, get dashboard data
Metamodel: Get the organization metamodel
Ardoq Tip: get a tip on using ardoq
Additionally there are some utility functions that can be used by the AI client but which may not be relevant for end users
Resolve entity name: Resolve a human-readable name to an ID for any kind of entity (Component, Report, Dashboard, Viewpoint). This allows the ID to be used in other tool requests
Current User: get the current user information
Q: Which system prompt should I use in my AI MCP client
A: The MCP tool descriptions contain the necessary instructions to you AI client on how to use the MCP server. But you can complement this with your own system prompt that explains the types of information you have in Ardoq and how that information can be used. We recommend that you do your own evaluation to see the effect of adjusting the system prompt. Our article about Contex Engineering may give even more clarity on to how to optimize the performance of your Ardoq MCP Server setup.
See the tool description for Ardoq Support Guide for more information.
Q: How are permissions enforced?
A: The permission model is enforced using the owner of the API token used in the MCP Server connection.
We strongly recommend you create a specific Service User (or multiple users) for accessing Ardoq via MCP. The permissions for each user should be limited to the specific information you want to make available from Ardoq. For example, create a Service User who only as access to particular reports and dashboards.
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 Ardoq?
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 does Ardoq return paginated information or a subset of information?
A: It is possible for large results from Ardoq, such as very large reports, to exceed the size that AI clients can handle.
AI clients have a limited context window for parsing information. That context window size can be different for each client. Therefore we limit the size of the returned results so that limit should not be exceeded. When requested information is too large then we paginate of filter some details from the results to. When that occurs we instruct the AI to inform the user and that the user can request the next page of results.
We test with a range of MCP clients and AI model providers but we cannot test for all combinations of clients and configurations. We have set the size of the returned information to match that of Microsoft Copilot Studio Agents. This is a popular AI client platform used by our customers. However, we note that this size can be noticeably smaller than the context window size provided by other AI providers. Please contact us on the Product Portal if you think we should be more flexible in allowable context windows.
Q: Why do I get an error message such as MaxTokenLengthExceeded? Is this a problem with the Ardoq MCP implementation?
A: Some AI clients may have a context window smaller than our pagination limit and may not be able to handle the size of information returned. In that situation an exception may occur. We recommend creating reports and viewpoints tailored to your use cases that return less information to avoid these kinds of situations.
Q: Why does the AI sometimes require confirmation before retrieving the requested information?
A: MCP testing has shown better evaluations when first asking the AI to reason about how to answer the question before selecting the required tools.
A drawback is that some AI clients will ask for confirmation to proceed after determining the reasoning but before calling the required tools. Simply saying "continue" or "ok" will trigger the client to continue
Q: Do some AI clients work better than others with Ardoq MCP ?
A: We test with a range of MCP clients and AI models. We have found significant differences in the ability for these clients to both call the correct tool and to interpret the resulting information. We have introduced significant tool instructions to help limit these differences but we have been unable to completely eliminate the differences.
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: How should I resolve what I consider to be errors?
A: It can be difficult to trace errors when Agents are communicating with MCP Servers.
Read and understand the article about Context Engineering
All of those tips are necessary to understand how Agents use MCP servers and what you can do to optimize the experience.
Ensure you have a connection to Ardoq MCP
Prompt: "give me a tip about Ardoq?". This will call the Ardoq Tip tool which returns a simple generic description about using Ardoq. This tool does not require authentication to call so can be useful to test the configuration of your client. Note: this tool does not access customer information. It simply returns some static generic text.
Prompt: "who am I in Ardoq?". This should call the current_user tool and return Ardoq User or Service User for the API token that is being used to access Ardoq. It is a useful tool for checking the authentication of your access token.
Make sure you have a clean context. Start a new chat or reset the session.
Ask your client for a list of preceding requests to ensure there is not other information. e.g., "which messages have I sent you?"
Check that you are limiting your Agent to only use Ardoq MCP to isolate potential issues from other tools
For example, disable non-Ardoq MCP tools and disable internet search if possible.
Examine the raw request and response from your client to the MCP Server.
Most clients let you examine request and response messages.
Remember that Ardoq MCP is simply providing data to your AI solution. The AI solution may be interpreting the data and summarizing it before showing you an answer to your prompt
Ask the AI to explain its reasoning.
The MCP server instructs the client to determine its reasoning, based on information on how to use the MCP server tools, before attempting to answer the question. Asking to show that reasoning can help identify where the AI may have identified the incorrect tool or make an incorrect inference about the returned information.
If you still believe there is an issue with the MCP server then share the specific prompt and request/response (if available) with Customer Support
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 accountsClick Create new
Fill in the required fields:
Service account name – e.g.,
Claude MCP AccessToken description – e.g.,
Used by Claude Desktop to access MCP serverService 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.
Requires a Claude Pro account to unlock full potential.
Requires a Microsoft 365 Copilot or Copilot Studio license to use.
Requires access to GitHub Copilot.
Requires a Perplexity Pro license and MacOS
Connect to Ardoq MCP with Claude Code CLI, OpenAI's Codex CLI, or Gemini CLI, directly in the terminal
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.
Known Issues
Change Log
2025-09-25
GA release help article
new tools, improved tool descriptions, and example prompts
updated system prompt to use
2025-06-26
SSE protocol deprecated.
New endpoint for MCP required. See FAQ
2025-05-09
Initial tech preview