Skip to main content

How to connect ChatGPT to Planhat, using OAuth and Planhat's MCP server

Steps to link OpenAI's ChatGPT to Planhat, via a Planhat OAuth Client and the Planhat MCP server

Written by Carly Hammond

Summary

  • It's easy to connect ChatGPT to Planhat via OAuth, so you can access your Planhat data from the ChatGPT interface

  • The main setup steps are:

    • Creating an app for Planhat in ChatGPT

    • Setting up an OAuth Client in Planhat

    • Publishing the app in ChatGPT to your ChatGPT workspace if desired

  • Each connecting user authenticates individually, with the permissions that can be authorized limited to those that are specified in both the OAuth Client and the user's Role in Planhat

Who is this article for?

  • Anyone who would like to learn about connecting ChatGPT to Planhat via OAuth, to access Planhat data from ChatGPT

  • It's particularly useful for Admins / Ops users who set things up for their Planhat tenant

Article contents

Introduction

You can use Planhat's MCP (Model Context Protocol) server to connect between your Planhat tenant and OpenAI's ChatGPT, or Anthropic's Claude, so you can ask AI queries in ChatGPT or Claude and it can securely access and operate on your Planhat data.

While it's possible to set this up using the legacy method of Planhat Private Apps (formerly called Service Accounts), the recommended method of authentication is using Planhat OAuth Clients.

In this article, we will take you through the steps to link your ChatGPT account to your Planhat account via a Planhat OAuth Client. The data access from ChatGPT is limited by the permissions you set in the OAuth Client and the Planhat Role permissions of each user authenticating.

📚 Further reading

We have additional documentation on related topics, which you can refer to for further details and context:

Prerequisites

  • You should be a Planhat user with access to the Planhat App Center (as that's where you set up OAuth Clients)

  • You also need a ChatGPT account. If you would like to publish the Planhat app/connection in ChatGPT at the end of the process, you should be on a Business, Edu or Enterprise plan, with admin or owner permissions

Stage 1: in ChatGPT, create an app for Planhat

  1. In ChatGPT, go to "Settings" (by clicking in the bottom left)

  2. Click on "Apps" and then "Advanced Settings"

  3. Enable "Developer mode"

  4. Click "Create app"

  5. This opens up a "New App" form to fill in:

    • "Name": enter a name for the app/connection, such as "Planhat"

    • "Description": optionally, you can add further details here

    • "Connection" - "Server URL": copy/paste in the following URL: https://api.planhat.com/v1/mcp

      • 📌 Important to note: if you will be connecting to a Planhat demo tenant (https://ws.planhatdemo.com/ instead of the usual https://ws.planhat.com/), then for this URL you should enter https://api.planhatdemo.com/v1/mcp instead, or this will lead to an error when authenticating later on in the process

    • "Authentication": keep this as "OAuth"

  6. Expand "Advanced OAuth settings" in this form (shown in the screenshot above, below the "Authentication" dropdown menu). This will open up the form like so:

    Click the image to view it enlarged

    • Under "Client registration", ensure "Registration method" is set to to "User-Defined OAuth Client" (shown above)

    • You will see your "Callback URL", in the format https://chatgpt.com/connector/oauth/[...]. Click the copy symbol next to this - you will paste this into a Planhat OAuth Client in the next setup stage

    • Do not close this screen in ChatGPT

Stage 2: in Planhat, create an OAuth Client

🚀 Tip

You may sometimes hear Planhat OAuth Clients referred to as "OAuth apps".

📚 Further reading

For more details on Planhat OAuth Clients in general, you can refer to our separate article here.

  1. In Planhat, go to the App Center, and click "+ New app"

    Click the image to view it enlarged

  2. In the Apps Library, click "+ OAuth Client"

    Click the image to view it enlarged

  3. Enter a "Name" for your OAuth Client (e.g. "ChatGPT Connector"), and click "Create"

    This will open up a form like so:

  4. Under "Application Profile" (which you can see in the screenshot above):

    1. Add a "Short Description" that will appear on the authorization screen (which you can see an example of later in this article). For example: "Planhat customer platform connector for ChatGPT"

    2. Optionally, you can add a "Logo"

    3. In the "Redirect URLs" field, paste in the "Callback URL" that you copied from ChatGPT in stage 1

  5. Click into the "Permissions" tab, and set the permission levels for the Planhat data models you want ChatGPT to be able to access via this connection

    • For instance, you could enable all permissions specifically for the Company model, as shown in the example screenshot below

    • When a user (you or a co-worker) authorizes ChatGPT to interact with their Planhat data via this connection, the permissions defined in the OAuth Client act as the maximum. The Role that the user has in Planhat also applies a limit - i.e. a user can't authorize greater permissions than those available in their Role. The "inclusive" OAuth scope, which is automatically applied when connecting ChatGPT to Planhat's MCP server, means that the permissions requested/granted in a user authorization are those in the overlap between the OAuth Client permissions and the Role permissions - e.g. if the OAuth Client has Company and End User permissions specified, while the Role has access to Company and Asset, then the authorization will request/grant access to Company (i.e. the intersection of the two sets of permissions)

    • (Alternatively, a Planhat "Super Admin" (staff member) could enable the "Enable dynamic permissions" toggle switch within the OAuth Client, which would mean that you don't define permissions in the OAuth Client, and instead, they are configured per authorization)

    • For further discussion of OAuth Client permissions, you can refer to our main OAuth Client articles here and here

  6. Clicking back into the "General" tab of the OAuth Client ...

    ... please note that for security reasons, the Client Secret is only shown once, so you should copy it now, and paste it into the "OAuth Client Secret" field in the form you still have open in ChatGPT (shown in the screenshot below). You may also wish to store it securely

  7. Copy the "Client ID" from the OAuth Client form in Planhat, and paste it into the "OAuth Client ID" field in the form in ChatGPT (also shown in the screenshot below)

  8. When you have finished configuring the OAuth Client in Planhat (and definitely after you have copied the Client Secret and pasted it into ChatGPT, because you will not be able to see the Client Secret in Planhat again after this point), click "Save" in Planhat

Click the image to view it enlarged

Stage 3: complete the app setup in ChatGPT

  1. In the ChatGPT form, select the checkbox and click "Create"

  2. This will open up a modal where you can initiate the authorization - click "Sign in with Planhat"

  3. You will see the standard OAuth Client authorization modal (as discussed in our main OAuth Client article here), where you can review the requested access level (e.g. full access to the Company model in the example below, as we set in the "Permissions" tab of the OAuth Client in an earlier screenshot). If you would like to proceed, click "Authorize"

    🚀 Tip: you can click "Show more" if you would like to see property/field details:

  4. After you've clicked "Authorize", you should be able to see in ChatGPT that this is now connected (like in the example below). You can now close this menu. (Note that you may need to refresh your window before you start using this connection in a chat with ChatGPT, to ensure it's available for use)

  5. To confirm that everything is working, start a new conversation in ChatGPT and try a simple query, such as: "List the Companies where Carly is the Owner"

Stage 4: (optionally) publish to your ChatGPT workspace

📌 Important to note

To have the option to publish, you should on a ChatGPT Business, Edu or Enterprise plan, with admin or owner permissions. You won't have this option if you set up the connection using your own Free plan.

Once the connection is verified, follow the instructions below if you would like to allow other users in your ChatGPT workspace to find and connect to it themselves.

  1. In ChatGPT "Settings", select "Apps" (i.e. go back to where you set up the connection)

  2. Find the Planhat app that you have just created, click "..." and then click "Publish"

🚀 Tip

Each ChatGPT user will then authenticate individually, using their own Planhat user account, on first use. As we described earlier in this article, the permissions you set in the OAuth Client in Planhat act as a maximum; if a connecting user has different permissions in their Planhat Role, they can authorize what's included in both the OAuth Client and their Role (the intersection) but nothing more. (Alternatively, the OAuth Client permissions can be set to be fully dynamic, and selected by each user within the authorization process.) For further discussion of OAuth Client permissions, you can refer to our main OAuth Client articles here and here.

Did this answer your question?