Skip to main content

MCP and OAuth Clients - Q&A and troubleshooting

FAQs and error messages related to ChatGPT and Claude connections

Written by Carly Hammond

Summary

  • By connecting with the "inclusive" scope (which now happens automatically with Planhat's MCP server), each individual user can authorize access to Planhat data corresponding to the intersection (overlap) between the permissions set in the OAuth Client and the permissions in their Role

  • When setting up an OAuth Client and AI app/connector in ChatGPT or Claude (following the instructions in separate articles) ensure you enter the correct URLs - we list some error messages you may see if you don't

Who is this article for?

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

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

  • It's also relevant to more general Planhat users authorizing using these connections

Series

The most related Help Center articles and documentation webpages are as follows:

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. This means 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.

📌 Important to note

For instructions on how to set up the connection for ChatGPT or Claude, please refer to these separate articles:

You can also refer to our MCP webpage (which is more general, and aimed mainly at technical/developer readers) here.

In this article, we go through some FAQs and troubleshooting tips related to MCP/OAuth connections for AI. If you still need more support, you can reach out to your Planhat contacts or our Support team.

Remember, first make sure you have followed the instructions in the articles linked to in the "Further reading" box above.

Questions and answers (Q&As)

  • Q: Does each connecting user within an organization need to create separate OAuth Clients etc. for ChatGPT or Claude?

    • A: No - an Admin Planhat user in your Planhat tenant can create an OAuth Client there (in the App Center), and then set up the connection on the AI side and share it with co-workers, who then each authenticate individually

  • Q: Can a user gain additional Planhat data access by using ChatGPT or Claude, compared to the Planhat data access in their Planhat Role?

    • A: No - each user connects to ChatGPT or Claude individually (albeit using an OAuth Client configured by their Admin), and can only authorize data access that they already have in their Role. (The permissions set in the OAuth Client also apply a limit)

  • Q: If a user tries to connect to ChatGPT or Claude, and they have fewer permissions enabled in their Role than were set by the Admin when configuring the OAuth Client, will that lead to a failure (error message)?

    • A: No - the OAuth scope that is now applied is "inclusive", which means that the user can authorize the intersection (overlap) of their own Role permissions and the OAuth Client permissions. (The older process used the "default" scope, which meant all the permissions specified in the OAuth Client were requested, and that did lead to a failure/error if a user without all those permissions tried to authorize)

  • Q: Is it possible to not set the permissions within the OAuth Client?

    • A: Yes - although the typical method is to specify permissions within the OAuth Client, it's possible to have an OAuth Client set to "dynamic permissions", where no permissions are specified in the OAuth Client, but instead they are chosen by each user when they authorize the connection. (They will only be able to select permissions in their Role.) Please speak to a Planhat staff member if you would like to enable this option. Note that if this setting isn't enabled for an OAuth Client, you do need to specify permissions within the OAuth Client.

  • Q: Can Planhat metrics be accessed via ChatGPT/Claude and MCP/OAuth?

    • A: MCP/OAuth is for Planhat data models (Company, End User, Conversation, Task and so on), rather than raw time-series data (user activities / custom metrics). However, it can access calculated metrics linked to a model, as they are like fields on that model. For example, a Company calculated metric is accessible as part of access to the Company model

Authorization errors

Let's take a look at some error messages you may come across when connecting between Planhat and ChatGPT/Claude via a Planhat OAuth Client and the Planhat MCP server. We explain the likely causes and how to solve them.

  • Invalid client_id: OAuth client not found.

    • Check the Planhat URL you have entered into ChatGPT (in "Connection" - "Server URL") or Claude (in "Remote MCP server URL"):

      • In most circumstances, this should be https://api.planhat.com/v1/mcp

      • However, if you connecting to a Planhat demo tenant (https://ws.planhatdemo.com/ instead of the usual https://ws.planhat.com/), then this should be https://api.planhatdemo.com/v1/mcp

  • Invalid redirect_uri: not registered for this client.

    • Ensure you have entered the correct URL in the "Redirect URLs" field in the OAuth Client in Planhat

      • For ChatGPT, you paste in the "Callback URL" that you copied from ChatGPT (following the instructions here)

        • This is unique to your own setup

        • It will be in the format https://chatgpt.com/connector/oauth/[...]

      • For Claude, enter https://claude.ai/api/mcp/auth_callback

  • You do not have any of the permissions this application requests.

    • Make sure you have enabled the desired permissions in the "Permissions" tab of the OAuth Client in Planhat - you can't leave this blank

  • OAuth permission check failed: missing permissions

    • This was an older error that you should no longer encounter. The way the permissions used to work was that:

      • If an admin set up an OAuth Client with lots of permissions ...

      • ... and then a general user, with fewer permissions in their Planhat Role than listed in the OAuth Client, tried to use it ...

      • ... the associated AI/MCP connection would use the "default" OAuth scope (which means all permissions in the OAuth Client would be requested) ...

      • ... and then the user would see this error when trying to authenticate, as due to not having all the permissions in their Role that were being requested

    • However, now AI/MCP connections work via the "inclusive" OAuth scope, which stops this error occurring:

      • The "inclusive" scope means that the user can authorize the intersection (overlap) between the permissions stated by the Admin in the OAuth Client, and the permissions in the user's Role

      • For example, if the OAuth Client has permissions for Company and Asset enabled, but the connecting user has permissions for Company and End User only, then the result will be that the Company permissions can be authorized (with no error)

      • This means the permissions set in the OAuth Client represent the maximum permissions that can be authorized (rather than it being all or nothing)

      • If you had previously set things up before the "inclusive" scope was introduced, you don't need to reconfigure your OAuth Client, but you should reconnect in ChatGPT/Claude

General MCP error codes

These are general error codes that you may encounter when using the Planhat MCP server, as listed in our MCP server webpage for developers here. These errors can apply whether you are connecting to the Planhat MCP server via an OAuth Client (recommended) or a Private App (Service Account - legacy method), both of which are configured in the Planhat App Center, and they are not specific to connections with AI tools (ChatGPT/Claude).

  • 401 Unauthorized

    • Cause: missing or invalid access token

    • Solution: check the Authorization: Bearer <token>/<token> and ensure token is active and valid

  • 403 Forbidden

    • Cause: token lacking permissions

    • Solution: update app permissions in the App Center

  • 404 Not Found

    • Cause: invalid MODEL_ROUTE or OPERATION

    • Solution: confirm supported models/operations using get_model_actions

  • 400 Bad Request

    • Cause: missing or invalid parameters

    • Solution: ensure types and required fields are correct by checking get_model_action_parameters

  • 429 Too Many Requests

    • Cause: rate limit hit

    • Solution: retry with delay; use Retry-After header if present

  • 500 Internal Server Error

    • Cause: unexpected server-side issue

    • Solution: retry the request; report to the Planhat team with request details if persistent

📚 Further reading

For further details of the Planhat MCP Server, please refer to the MCP webpage here.

Did this answer your question?