Connecting your assistant

Add GPS's connector to Claude, ChatGPT or another MCP client, then sign in to GPS and approve it.

View as Markdown Open in Claude Open in ChatGPT

Before you start#

You need an Empiraa GPS account. The connector is included on every GPS plan. Each person connects their own assistant, with their own GPS sign-in.
Each organization's admins decide whether assistants may be used there at all, and whether they may make changes. See Admin controls.
Any assistant that can add a remote MCP connector with sign-in (OAuth) can connect. The steps for the most common ones are below.

The connector URL#

Text

https://plan.empiraa.app/mcp

Admins can also copy it in GPS, under Settings › Developer › Claude & ChatGPT, beside the steps below.

Claude on the web#

In Claude, open Connectors (under Customize or Settings) and choose Add custom connector.
Name it Empiraa GPS and paste the connector URL.
Select Add, then Connect, and sign in to GPS when it asks.
Choose what Claude can do in GPS, then select Allow.

On a Claude Team or Enterprise plan, an owner adds the connector for everyone first. You then find it under Connectors and select Connect.

Claude desktop and mobile#

Claude's desktop and mobile apps sign in to GPS through your Claude account, so a connector you've added in Claude on the web is there too. If a chat doesn't reach GPS, check that Empiraa GPS is turned on for that chat.

ChatGPT on the web#

In ChatGPT on the web, turn on Developer mode in Settings.
Create a new app or connector, name it Empiraa GPS and paste the connector URL.
If it asks how to sign in, choose OAuth. Create it, then sign in to GPS when it asks.
Choose what ChatGPT can do in GPS, then select Allow.

On a ChatGPT Business or Enterprise workspace, an admin may need to allow Developer mode or add the app for you.

Claude Code#

Add GPS from a terminal:

Shell

claude mcp add --transport http empiraa-gps https://plan.empiraa.app/mcp

Start Claude Code, type /mcp, choose empiraa-gps and select Authenticate. Your browser opens GPS.
Sign in if asked, choose what Claude Code can do, and select Allow.

Claude Code receives its sign-in on your own computer (a loopback address), so GPS shows it as an app on this device rather than as Verified.

Cursor#

Open Cursor Settings, go to MCP (Tools & Integrations) and add a new MCP server. Cursor opens its mcp.json file.

Add GPS and save:

JSON

{
  "mcpServers": {
    "empiraa-gps": { "url": "https://plan.empiraa.app/mcp" }
  }
}

Back in Cursor Settings, select the sign-in button beside empiraa-gps. Your browser opens GPS, where you approve the connection.

VS Code with GitHub Copilot#

Open the Command Palette and run MCP: Add Server.

Choose HTTP, paste the connector URL and name it empiraa-gps. Or add it to .vscode/mcp.json:

JSON

{
  "servers": {
    "empiraa-gps": { "type": "http", "url": "https://plan.empiraa.app/mcp" }
  }
}

When VS Code asks to sign in, allow it, then approve the connection on GPS's screen.
In the chat, choose Agent mode. GPS's tools are in its tools list.

Each app's menus change from time to time. If a step reads differently, look for the app's connector or MCP settings.

Other MCP clients#

Any client that supports MCP's streamable HTTP transport and its OAuth authorization flow can connect. It finds GPS's sign-in endpoints from the connector URL and registers itself (dynamic client registration, or a client ID metadata document), so there's no client ID to request. The details are in How it works.

Approving the connection#

When your assistant sends you to GPS, sign in if asked. GPS then shows one page, which you have 10 minutes to answer.

Who is asking. The app's name, and the address GPS will send you back to. Verified appears only beside Claude or ChatGPT, and only when GPS has confirmed the sign-in goes back to them. Any other app carries a warning that GPS can't confirm who made it, since any app can call itself anything. An app on your own computer, such as Claude Code, is marked as one: only continue if you just started the connection from an app there.
Who you're signed in as, with Sign out if it's the wrong account.
What it can reach: every organization you can open in GPS, including myPortal client accounts. It sees only what you can see, and each organization's admins can turn assistants off.
What it can do: View only, or View and make changes. If the app asked only to view, only View only is offered.
Default organization: the one it uses when you don't say which organization you mean, or No default, so it asks which one. It can still reach all of them.

Select Allow to connect, or Cancel if you didn't expect the request. Allow becomes available a moment after the page opens, once you move the pointer or press a key such as Tab. The connection stays until you disconnect it.

View only, or View and make changes#

View only: it can read what you can see in GPS. It's never shown the tools that make changes. If it tries one anyway, GPS refuses with insufficient_scope and tells it to reconnect with View and make changes. Some assistants, such as ChatGPT, then offer to reconnect for you.
View and make changes: it can also add and update things in GPS, as you. It can never delete anything, except removing an empty position from your org chart.

You can narrow a connection to View only at any time in Connected apps, and it takes effect straight away. To let it make changes again, connect it again. A connection never gains the right to make changes without a fresh approval.

The default organization#

Every tool acts in one organization at a time. A tool that's given an organization uses it. One that's given an item, such as an objective, uses the item's own organization. Otherwise it uses your default. With no default, your assistant asks you which organization you mean. list_organizations lists the ones your connection can reach.

You can change the default later in Connected apps.

Your first prompts#

GPS's Claude & ChatGPT settings page suggests three first prompts built from your own plan, such as one about a goal that's off track or an objective of yours. Without plan data it suggests ones that work for anyone:

"What's off track in our plan?"
"Check in my latest numbers from my spreadsheet"
"What should I focus on this week?"

Ready-made prompts such as Review the week in our plan also appear in assistants that show prompts. See Prompts, resources and widgets.

Managing and disconnecting#

Settings › Profile › Connected apps lists each assistant you've connected, with its access and default organization. For each one you can:

change its default organization;
Switch to view only, which takes effect straight away;
see its Recent changes;
Resume it, if GPS paused it;
Disconnect it. It stops working with GPS straight away. Anything it already added or changed stays as it is. To use it again, connect it again from the assistant.

The same page has My AI changes: what your assistants have added or changed in GPS, in every organization, newest first, with Undo where a change can be undone.

Also:

Changing your GPS password disconnects every assistant connected to your account.
GPS pauses a connection that makes an unusual number of changes, or keeps being refused or failing, and tells you in GPS. It can't do anything until you resume it, and resuming needs no reconnect. See Safety and privacy.
A connection left unused for 30 days may need to sign in to GPS again, because its refresh token lapses. One in use never does. See How it works.