Skip to main content

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

Steps to link Anthropic's Claude to Planhat, via a Planhat OAuth Client and the Planhat MCP server

Written by Carly Hammond

Summary

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

  • The main setup steps are:

    • Setting up an OAuth Client in Planhat

    • Creating a connector for Planhat in Claude

    • Authorizing the connection

  • 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 Claude to Planhat via OAuth, to access Planhat data from Claude

  • 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 Anthropic's Claude or OpenAI's ChatGPT. This means you can ask AI queries in Claude or ChatGPT, 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 Claude account to your Planhat account via a Planhat OAuth Client. The Planhat data accessible from Claude is limited by both 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

Stage 1: 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 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. "Claude 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 Claude"

    2. Optionally, you can add a "Logo"

    3. In the "Redirect URLs" field, enter https://claude.ai/api/mcp/auth_callback

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

    • 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 Claude 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 Claude 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 in Planhat, so you should copy it now, for pasting into Claude. You may also wish to store it securely

    • If you went to look at it in Planhat later, the only option would be to generate a new Client Secret, which would mean that the previous Secret would stop working and existing connections would be disconnected

  7. When you have finished configuring the OAuth Client in Planhat - and definitely after you have copied the Client Secret - click "Save". Do not close this OAuth Client modal, as you will (after pasting the Client Secret into Claude) need to copy the Client ID

Stage 2: in Claude, add connector

  1. In Claude (claude.ai), go to "Customize", and click on "Connectors"

  2. Click "+" ("Add connector")

  3. Click "Add custom connector"

    That will open up a form like this:

  4. Fill in the following fields

    1. "OAuth Client Secret": paste in the Client Secret you copied from the OAuth Client

    2. "Name": Planhat

    3. "Remote MCP 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

    4. "OAuth Client ID": copy from the OAuth Client in Planhat and paste in here

  5. Click "Add"

Stage 3: in Claude, authorize the connection

  1. Still in Claude (claude.ai), you will see a message like the one shown below. Click "Connect"

  2. 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:

  3. After you've clicked "Authorize", your Planhat connection will show as connected within Claude. As default, you will see tool permissions listed as "Needs approval", but you can edit this in Claude (to "Always allow" or "Blocked"), on a bulk or granular level, as desired

    Click the image to view it enlarged

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

🚀 Tip

Once you (as an Admin) have set this connection up in Claude, then your co-workers can also use it. Each Claude user will authenticate individually, using their own Planhat user account, on first use. To do this, in Claude, each user goes to "Customize" --> "Connectors" (where the Planhat connector was set up) and they will see the Planhat connector listed (as "Not connected") - they can click "Connect" to initiate the authorization flow.

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?