MCP Server

Discover models and operations

Discover available Planhat data models and their supported operations for API exploration and dynamic tool configuraiton. The output is a JSON arary of model routes with supported operations.

Get model parameter schema

Retrieve detailed parameter schemas for specific model-operation combinations, for schema validation, form generation and parameter discovery. Output is JSON schema with parameter definitions, types and requirementst. Use following as input:

• MODEL_ROUTE : Target data model (E.g. Companies)

• OPERATION: Desired operation ("create"/"update"/"view"/"list")

Perform operations

Execute CRUD (Create/Read/Update/Delete) operations on Planhat data, for all types of data manipulation. Output is API response, use the following as input:

• MODEL_ROUTE: Target data model

• OPERATION: Operation type

• PARAMETERS: JSON string containing operation data

  
  

Access token

1. Go to App Center, and create a new private app.

2. Assign the necessary permissions to the app based on your access needs.

3. Generate an access token and use it to authenticate MCP requests. See example.

401 Unauthorized

Caused by missing or invalid access token. Check the Authorization: Bearer <token>/<token> and ensure token is active and valid.

403 Forbidden

Caused by token lacking permissions. Solve by updating app permissions in App Center.

404 Not Found

Caused by invalid MODEL_ROUTE or OPERATION. Fix by confirming supported models/operations using get_model_actions.

400 Bad Request

Caused by missing or invalid parameters. Ensure correct types and required fields are correct by checking get_model_action_parameters.

429 Too Many Requests

Rate limit hit. Retry with delay, use Retry-After header if present

500 Internal Server Error

Unexpected server-side issue. Retry the request, report to Planhat Team with request details if persistent.

Prerequisite

1. A Planhat account with access to App Center (required to create OAuth apps)

2. A ChatGPT account on Buesiness, Edu or Enterprise plan with admin or owner permissions

Step 1: Enable Developer mode and create Planhat App in ChatGPT

1. In ChatGPT, go to Settings → Apps → Advanced Settings, enable Developer Mode. Navigate to Settings → Apps → Create

2. Once new app form opens, enter

   1. Name: e.g. Planhat, description optional

   2. MCP Server URL: https://api.planhat.com/v1/mcp

   3. Authentication: OAuth

3. Expand Advanced Settings,

   1. Set Registration method to User-Defined Oauth Client in Client registration

4. You will now see Callback URL, e.g. https://chatgpt.com/connector/oauth/..

5. Click copy, you need this in the next step. Do not close this screen

The Callback URL is unique for your connector. If this value is missing or incorrect, the OAuth flow will fail with Invalid redirect_uri.

Step 2: Create an OAuth app in Planhat

1. In Planhat, go to App Center → New App → OAuth Client

2. Give it a name, for example "ChatGPT Connector"

3. Under Application Profile, add a short description that will appear on the authorization screen. For example: "Planhat customer success platform connector for ChatGPT"

4. Optional: Add a logo

5. Set the permission levels for the Planhat data models you want ChatGPT to access

6. In the Redirect URLs field, enter Callback URL coped from step 1

Step 3: Save and copy your credentials

1. Click Save. Planhat will generate two values

   1. Client ID - a public identifier for your app (starts with pk_..)

   2. Client Secret - a private key shown only once (starts with sk_..)

2. Copy the Client Secret and store it securely. Planhat will not show it again after you leave the screen. If you don't have it saved, you will need to generate a new one and existing connections will be disconnected.

Step 4: Complete app setup in ChatGPT

1. Switch back to ChatGPT

2. In the Oauth advanced settings panel, enter the credentials from Planhat

   1. Client ID: Your ID starting with pk_.. from credentials

   2. Client Secret: Your secret starting with sk_.. from credentials

3. Click Create

Step 5: Verify connection

To confirm that everything is working, start a new conversation in ChatGPT and try a simple query: "Show me my top 3 companies in Planhat by ARR"

Step 6: Publish to your workspace

Once connection is verified, follow the instructions below to allow users in your workspace to find and connect to the app themselves. Each user authenticates with their own Planhat account on first use, access is always scoped to their individual permissions. Restrict this with role-based access control.

1. Go to Workspace Settings → Apps

2. Find the Planhat app and click Publish

   
   

Prerequisite

1. A Planhat account with access to App Center (required to create OAuth apps)

2. A Claude account on a Pro, Team, or Enterprise plan

3. Access to your Planhat workspace's Settings area

Step 1: Create an OAuth app in Planhat

1. In Planhat, go to App Center → New App → OAuth Client

2. Give it a name, for example "Claude Connector"

3. Under Application Profile, add a short description that will appear on the authorization screen. For example: "Planhat customer success platform connector for Claude"

4. Optional: Add a logo

5. Set the permission levels for the Planhat data models you want Claude to access

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

Step 2: Save and copy your credentials

1. Click Save. Planhat will generate two values

   1. Client ID - a public identifier for your app ( pk_..)

   2. Client Secret - a private key shown only once ( sk_..)

2. Copy the Client Secret and store it securely. Planhat will not show it again after you leave the screen. If you don't have it saved, you will need to generate a new one and existing connections will be disconnected.

Step 3: Add connector in Claude.ai

1. Go to claude.ai and open Settings

2. Navigate to Connectors (or Integrations, depending on your plan)

3. Click Add Connector and select Custom OAuth

4. Fill in the following fields

   1. Name: Planhat

   2. Remote MCP Server URL: https://api.planhat.com/v1/mcp

   3. Client ID: Your ID starting with pk_.. credential from step 2

   4. Client Secret: Your secret starting with sk_.. credential from step 2

5. Click Save

Step 4: Authorize connection

After saving, Claude will redirect you to a Planhat authorization screen

1. Review requested permissions and then click Authorize

2. You will be redirected back to Claude

3. Your Planhat connection will appear as Connected in your integrations or connectors list

Step 5: Verify connection

To confirm that everything is working, start a new conversation in Claude and try a simple query: "Show me my top 3 companies in Planhat by ARR"

Prerequisite

1. A Planhat account with access to App Center (required to create Private Apps)

2. A Claude account on a Pro, Team, or Enterprise plan

3. Access to your Planhat workspace's Settings area

Step 1: Get your Planhat API token

1. Navigate to App Center in Plahat

2. Create a new private app

3. Assign the necessary permissions

4. Generate and copy your access token

Step 2: Locate and Edit the Configuration File (MacOS)

1. Open Finder

2. Press Cmd + Shift + G

3. Type ~/Library/Application Support/Claude/

4. Locate claude_desktop_config.json.

5. If it doesn't exist, create a new file with this name. Open with Text Editor

Step 2: Locate and Edit the Configuration File (Windows)

1. Open File Explorer

2. In address bar, type %APPDATA%\Claude\

3. Locate claude_desktop_config.json.

4. If it doesn't exist, create a new file with this name. Open with Text Editor

Step 3: Add Planhat MCP Configuration and Replace Token

1. Add the JSON for empty or existing configuration.

2. Find and replace token with the Planhat API token

3. Save file

Step 4: Restart Claude Desktop and Refresh MCP Configuration

1. Restart Claude Desktop

2. Press "Reload MCP Configuration". If it's not visible in developer tab, go to "Help" / "Troubleshooting" / "Enable developer settings"

Step 5: Verify Setup

1. Verify hammer/connection icon in bottom right corner of chat input box

2. Press to see available MCP servers

3. Verify Planhat is listed

4. Alternatively, go to "Settings" / "Developer" tab to see if the server is running

Troubleshooting

• Make sure NPX is downloaded

• If MCP icon doesn't show, verify syntax in claude_desktop_config.json

• Verify the API token provided by private app in Planhat

• Restart Claude Desktop