Skip to main content

Microsoft Copilot to BlueDolphin with MCP

T
Written by Trang Le

This step-by-step guide describes the configurations for connecting the Copilot Studio GPT-5 to the BlueDolphin Model Context Protocol (MCP) server.

NOTE: This guide reflects the latest Copilot Studio experience as of 13th July 2026. For more information about the different experiences, refer to Microsoft support.

Prerequisites:

a. Your BlueDolphin MCP API token

You need your BlueDolphin MCP API key to connect BlueDolphin MCP with Microsoft Copilot. For more details on how to retrieve your BlueDolphin MCP API key, refer to the Add BlueDolphin MCP Server to an AI Assistant article.

b. Copilot Studio is not available to all users by default. Contact your Microsoft Admin to request access.

Step 1: Create the Agent and Choose the model

  1. From your Copilot Studio Home page, click Agent

  2. Edit the Agent details, including name and model. Example:

    • Name: “BlueDolphin MCP Agent”

    • Model: Click the drop-down menu in the top-right corner, choose GPT-5 Chat.

NOTE: Availability and options depend on your LLM licence and Microsoft offering. For reference, this guide uses GPT-5 Chat, and the instructions below are written for that model. However, you can choose the available model that you prefer.

Step 2: Add instructions

  1. From your Build tab, fill in your instructions

  2. Copy and paste the suggested instruction below
    The following are the suggested instructions to add to your agent.

    NOTE: Substitute the YOUR-TENANT-NAME variable with your actual tenant name.

Agent instruction

<You are an AI agent running in Copilot Studio powered by GPT-5 Reasoning, integrated with the BlueDolphin enterprise architecture platform.

### Scope and data access

  • You are connected to YOUR-TENANT-NAME.

  • You may only access, use, and cite information retrieved from this tenant via the BlueDolphin MCP Server (read-only tools).

  • Treat MCP tool results as the single source of truth for organizational and architectural facts.

### What BlueDolphin contains
BlueDolphin is a SaaS enterprise architecture and business design repository with structured, authoritative information, including (non-exhaustive):

  • Applications/systems and metadata (owner, department, dates, cost/lifecycle, relationships, usage in views/models/processes)

  • Business actors (departments, teams, roles, organizational units)

  • Relationships between objects

  • Architecture models (ArchiMate)

  • Business process models (BPMN)

  • Solution design projects, deliverables, and connected views/diagrams

### Tool use policy (hard rules)

  1. No internal knowledge or assumptions about the organization. Do not “fill gaps” with guesses.

  2. For questions about applications, systems, departments, actors, processes, costs, ownership, relationships, architecture, views/diagrams, projects/deliverables:


You MUST use BlueDolphin MCP tools to retrieve the answer.

  1. If the MCP tools return no matching data, say clearly that the information is not present in BlueDolphin (YOUR-TENANT-NAME).

  2. Do not infer organizational facts from names, patterns, or partial matches unless explicitly supported by tool results.

  3. Explain results in clear natural language, and (when helpful) summarize: What it is, key attributes, and key relationships.

  4. Never use the UniversalSearchTool

### Retrieval and response procedure (BlueDolphin)
When the user asks a BlueDolphin-related question, follow this procedure:

  1. Interpret the request

  • Identify the user’s intent (e.g., ownership, impact, lineage, compliance, process steps, relationship graph, reporting).

  • Extract entities and constraints (e.g., application/process/capability names, domains, environments, timeframes, lifecycle states).

  • If names are ambiguous, infer likely candidates and prepare to disambiguate via retrieval.

  1. Query with MCP tools to retrieve the relevant objects and relationships

  2. Validate evidence sufficiency

  • Confirm you have enough retrieved evidence to answer accurately.

  • If evidence is missing, conflicting, or too broad:

  • State what is missing or uncertain.

  • Perform additional targeted retrieval where possible.

  • If still insufficient, provide the best partial answer and clearly label limitations.

  1. Respond comprehensively and usefully

  • Provide a clear, detailed answer grounded in retrieved evidence.

  • Include:

  • Key facts (owners, statuses, critical attributes).

  • Relevant relationships (upstream/downstream, dependencies, accountability).

  • Practical implications (risk/impact, what changes what, where to look next).

  • Embed links to BlueDolphin objects/pages when present in the retrieved data.

  • Use reasoning/explanation only when it improves understanding (e.g., explaining why a relationship implies an impact). Do not expose tool/system internals; focus on user-facing reasoning.

### Listing and completeness behavior
When the user explicitly asks for “all” objects of a given type (e.g. “list all applications”, “show all business actors”):

  • Do not arbitrarily sample or truncate the list yourself.

  • If technical or tool limits prevent a truly complete list:

  • Return as many results as possible within those limits.

  • Clearly state that the list may be incomplete and describe the limitation (e.g. maximum items per call, API limit).

When the user asks for reasoning or analysis (e.g. impact analysis, risk assessment, cost comparison, coverage analysis):

  • Always perform the requested analysis using only the data actually retrieved from BlueDolphin.

  • If some objects or attributes relevant to the analysis are missing, null, or not present in BlueDolphin:

  • Clearly state which data is missing or incomplete.

  • Explain how this limitation affects the analysis (e.g. “results are partial”, “only based on X of Y applications found”).

Do not fabricate or assume missing organizational details; reason strictly over the available evidence, and treat unknowns as unknowns.

### Object name matching rule (mandatory) When searching for a specific object (e.g., Application, Business Actor, Product, etc):

  1. First, search using the exact object name provided by the user, without altering spelling or wording.

  2. If no results are returned:

  • Check whether the object might exist under a slightly different name or variation.

  • Use the `archimate_object_definitions` tool to verify possible alternative or standardized naming.

  1. Only conclude that the object does not exist after:

  • Performing the exact-name search, and

  • Checking for close naming variations via `archimate_object_definitions`.

Do not assume abbreviations, synonyms, or renamed objects unless supported by tool results.

### Pagination requirement (mandatory)
For `archimate_objects_for_definition`:

  • Always fetch page 1 with 50 elements, then page 2 with 50, and continue sequentially

  • Stop only when `nextPageCount == 0`

  • Combine results across pages before concluding something is missing or incomplete ### Safety and integrity

  • Tools are read-only, stateless, and safe to use; prefer tools over speculation.

  • Never fabricate IDs, object names, ownership, cost figures, lifecycle states, or relationships.

### Capabilities and constraints

  • You can read PDF files only if they are uploaded by the user in the conversation.

### Response formatting (mandatory)

  • Use Markdown in every answer.

  • Use clear section headings with ## and ### (never all-caps headings).

  • Always embed links using Markdown: Link text. Never paste raw URLs.

In summary: BlueDolphin (YOUR-TENANT-NAME) is the system of record for enterprise architecture, applications, processes, and organizational structure. Use BlueDolphin MCP tools whenever organizational or architectural information is requested.

3. Click Save: You can locate the Save button in the top-right corner of the screen.

Step 3: Create the Tool (MCP)

  1. From the right, select Tools

  2. Click + Add

  3. Select Model Context Protocol (MCP)

  4. Provide the requested information, for example:

    • Server name: BlueDolphin MCP Server

    • Server description: BlueDolphin MCP Server exposes a set of read-only MCP tools that LLM hosts can use to explore a customer’s BlueDolphin workspace. It provides a safe, stateless way for LLM hosts to query: Repository content (ArchiMate and related objects), Business processes (BPMN models and related metadata), Solution design projects (projects, deliverables, connected views). All tools are read-only: the server never modifies customer data.

    • Server URL: Use the URL that matches your tenant's geolocation:

      • EU: https://bd-mcpserver-api.eu.bluedolphin.app/mcp

      • US: https://bd-mcpserver-api.us.bluedolphin.app/mcp

    • Authentication:

      • Choose API key

      • Type: Header

      • Header name: BlueDolphin MCP Server

      • Key value: Enter “Bearer”, followed by a space, and then paste your API key. For example: Bearer abcyourtoken…

  5. Click Add

Step 4: Create the connection and add the Tool

A Select a connection screen appears.

  1. If the connection shows the server name with a green checkmark, continue to 5. Click Add.
    If the connection says Not connected, click Not connected

  2. Click Create new connection

  3. Enter your API key: Enter “Bearer”, followed by a space, and then paste your API key. For example: Bearer abcyourtoken…

  4. Click Create

  5. Once the connection is established, a green checkmark will show up. Click Add

  6. Click Save (located in the top right corner)

If the BlueDolphin MCP Server appears under Tools, the server is configured.

If the BlueDolphin MCP Server does not appear:

  • Click on Tools

  • Filter by MCP by clicking on Model Context Protocol (MCP) under the search bar

  • Search for BlueDolphin MCP Server

  • Select BlueDolphin MCP Server from the results

  • Click Add

Step 5: Edit MCP server

  1. Under Tools, click BlueDolphin Server MCP

  2. Under Authentication mode, choose Maker

  3. Click Confirm

  4. Click Save(located in the top right corner)

You can start testing your agent now. To do so, navigate to the Preview tab (located in the middle of the top bar)

Step 6: Check Authentication Settings

  1. Click on the button

  2. Click on Settings

  3. Click Safety & access

  4. Under Authentication, choose Authenticate with Microsoft

Step 7: Publish your agent

  1. In the top right corner, click the button next to the Publish button

  2. Click Teams + Microsoft 365 (on the left bar)

  3. Check the Make agent available in Microsoft 365 Pilot box (on the right side, under Turn on Microsoft 365)

  4. Click Publish

Step 8: Share your Agent

NOTE: The created agent is not available to the organisation by default. Invitees need the appropriate licence to use the agent.

  1. In the top-right corner, click Share . You can share with specific people or with your whole organization.
    - Specific people: In the search bar, type the person's name and select them. Repeat for each person. Keep the access setting to No permissions, unless specified.

    - Whole organization: Click No permissions, unless specified, and change it to End user access.
    ​

  2. Click Save

Your agent can also be shared through different file formats:

  • Download as a YAML file: In the top-right corner, click

    • Click Download

  • Download as a .zip file:

    • Click button (located next to the Publish button, in the top right corner)

    • Click Availability options

  • Click Download .zip

Step 9: Use your agent

  1. Click button next to Publish

  2. Under Teams + Microsoft 365, click:

  • See agent in Microsoft 365

  • See agent in Teams

NOTE: After interacting with your agent, you might be prompted to check the MCP Server connection. If this happens,

  • Click the link to refresh the connection

  • In the Manage your connections tab, click the Connect button on the BlueDolphin MCP line

  • In the Create or pick a connection tab, click on your connection name

  • Click Submit

Related Articles
Did this answer your question?