Introduction
The Cupix Compass Model Context Protocol (MCP) server lets a Microsoft Copilot Studio agent read your CupixWorks project data and answer questions about it in natural language. This article walks a Team Admin through connecting the Compass MCP server to a Copilot Studio agent, enabling its tools, testing it, and publishing it to Microsoft Teams and Microsoft 365 Copilot.
Note: Team Admin permission is required to create a Compass agent for your team.
Prerequisites
Before you start, make sure you have:
- A Microsoft 365 Copilot license assigned to the Team Admin.
- The Environment Maker or Agent Author role in the target Copilot Studio environment.
- Team Admin permission in CupixWorks.
- Your Cupix team domain and a Cupix account (email and password) with access to CupixCompass.
- Access to the mailbox for that Cupix account. Sign-in requires a verification code sent by email.
How It Works
The setup has six stages. The steps below map to them in order.
| Stage | What happens |
|---|---|
| License | Assign a Microsoft 365 Copilot license to the Team Admin. |
| Role | Grant that admin the Environment Maker or Agent Author role in the Copilot Studio environment. |
| Create | The admin creates a new agent in Copilot Studio. |
| Connect | Add the Compass MCP server as a tool and authenticate with Cupix. |
| Test | Run a test prompt to confirm the tools respond. |
| Publish | Publish the agent to Teams and Microsoft 365 Copilot for the team to use. |
Create the Agent
1. Sign in to Copilot Studio
Go to https://copilotstudio.microsoft.com/ and sign in with your account.
2. Create a blank agent
Click Create blank agent.
3. Name the agent
Enter the agent name you want your team to see, then click Create.
Note: Agent names must be unique within the environment. If the name is already taken, Copilot Studio asks you to choose another one.
Add the Compass MCP Server
4. Open the Tools tab
On the agent page, open the Tools tab.
5. Add a tool
Click Add a tool.
6. Select Model Context Protocol
Under Create new, click Model Context Protocol.
7. Enter the server details
Fill in the fields using the values below, then set Authentication to OAuth 2.0.
| Field | Value |
|---|---|
| Server name | Any string |
| Server description | Any string, at least 30 characters |
| Server URL | https://mcp.cupix.works/mcp |
| Authentication | OAuth 2.0 |
| Type | Manual |
| Client ID | 23v6aajn18senmur7gc0jfjuua |
| Client secret | Any string |
| Authorization URL | https://accounts.cupix.works/authorize |
| Token URL template | https://accounts.cupix.com/api/v1/tokens/refresh |
| Refresh URL | https://accounts.cupix.com/api/v1/tokens/refresh |
| Scopes | Leave empty |
| Redirect URL | Generated automatically when you save |
Note: The Authorization URL uses the cupix.works domain and the Token and Refresh URLs use the cupix.com domain. Enter them exactly as shown.
8. Set the type to Manual
Under Type, select Manual, then enter the Client ID, Client secret, Authorization URL, Token URL template, and Refresh URL from the table above.
9. Create the server
Scroll to the bottom of the form and click Create.
Connect Your Cupix Account
10. Continue to the connection step
When the tool is created, click Next.
11. Create the connection
Optionally enter a display name for the connection, then click Create. A Cupix sign-in window opens.
12. Enter your team domain
In the Cupix sign-in window, enter the team domain you use in CupixCompass, then click Next. Complete the sign-in with your Cupix email, your password, and the verification code Cupix emails you.
13. Add and configure the tool
When the connection status changes to connected, click Add and configure.
Enable the Compass Tools
14. Enable all tools
The Compass server exposes the tools below. New tools are off by default.
| Tool | What it does |
|---|---|
| list-my-projects | Lists the construction projects the user can access within a team. |
| ask-about-project-data | Queries the construction project database using natural language (Text-to-SQL). |
| set-focus-project | Saves the user’s current team and project so later tool calls can omit the team and facility arguments. |
| check-current-project | Returns the currently saved team and facility for the user. |
| search-site-photos | Searches 360° captures by visual content analysis — what is visually seen in the capture. |
| analyze-progress-and-forecasts | Analyzes Work In Place progress from SiteInsights, including completion rates, delays, and forecasts. |
Turn on the toggle in the Tools header row to enable every tool at once, or turn on each tool individually.
15. Save the tool
Click Save.
Test the Agent
16. Run a test prompt
Open the Test your agent panel and enter a prompt such as List my teams. The agent calls the matching Compass tool and returns your data.
Publish to Teams and Microsoft 365 Copilot
When the test prompt works, publish the agent so team members can use it, then follow the Microsoft guides below to roll it out.
| Task | Microsoft guide |
|---|---|
| Channels > Teams and Microsoft 365 Copilot > Make agent available > Add channel | Connect an agent to Teams and Microsoft 365 Copilot |
| See agent in Teams > Add | Install an agent in Teams and Microsoft 365 Copilot |
| Grant the "User - can use the agent" permission to users or security groups | Share an agent for chat |
| Availability options > Copy link | Share a link so others can install an agent |
| Expose the agent to shared users in the Teams App Store | Show to shared users in Teams |
| Submit for admin approval to deploy across the organization | Submit an agent for admin approval |
Troubleshooting
The agent replies that it needs a connection
If the agent replies with the message below, the connection is not authenticated yet. Click Open connection manager in the message.
“Let’s get you connected first, and then I can find that info for you. Open connection manager to verify your credentials. Once the connection is ready, retry your request.”
In Manage your connections, find the Compass connection. If the status is Not Connected, click Connect and sign in again.
Return to the chat and click Retry. The agent runs the prompt again using the restored connection.