Skip to main content

Planhat

Planhat's official MCP server gives agents access to your Planhat workspace as the signed-in Planhat user: list, search, create, update and delete records on any data model (companies, end users, conversations, tasks, custom models), and read, create and search Document Pages. The endpoint is https://api.planhat.com/v1/mcp over HTTP.

Planhat does not support dynamic client registration, so an admin creates a Planhat OAuth Client once and gives Willow its client ID and secret. Each person then signs in with their own Planhat account.

Setting up​

  1. Create an OAuth Client in Planhat. In Planhat, open App Center, click + New app, then + OAuth Client. Enter a name (for example Willow) and click Create.

  2. Get the redirect URL from Willow. In Willow, go to MCP Servers → + Add MCP server, find the Planhat card with the Official badge, and click + Use. Copy the redirect URL shown in the setup step, and keep this screen open.

  3. Finish the OAuth Client in Planhat.

    • Redirect URLs: paste the Willow redirect URL you just copied.
    • Permissions: open the Permissions tab and set the access level for each data model you want agents to reach. These permissions are the maximum. Each user can authorize only the overlap between them and their own Planhat Role. If Enable Admin-level Permission Control is turned off, you set no permissions here and each user chooses them when they authorize.
    • Copy the Client Secret from the General tab before you save. Planhat shows it once. A new secret disconnects existing connections.
    • Click Save, then copy the Client ID (it starts with pk_).

  4. Enter the credentials in Willow. Paste the Client ID and Client Secret, then complete the setup.

  5. Authorize. Complete the Planhat sign-in prompt, review the requested access, and click Authorize.

note

Planhat doesn't support dynamic client registration, so you must create the OAuth Client yourself before connecting. Willow requests the inclusive scope, which is the only scope the server advertises.

Everyone else in your organization who uses the server signs in individually with their own Planhat account. They don't need their own OAuth Client.

What agents can do​

Planhat's server exposes generic record tools that work across data models:

  • Discover: get_model_action_parameters returns field names, types and required flags for a model. Use it before creating or updating records or building filters.
  • Read: list_model_records (filter, sort, limit, offset, select), get_model_record, and search_records for full-text discovery across models.
  • Write: create_model_record, update_model_record, delete_model_record.
  • Documents: create_document, get_document, search_documents.

The server supports writes, including deletes. Planhat recommends granting only the permissions a workflow needs, starting read-only while testing, and avoiding delete permission unless you have a controlled use case. Set that in the OAuth Client's Permissions tab.

Troubleshooting​

"Invalid client_id: OAuth client not found."​

Cause: Planhat can't find an OAuth Client for the client ID you entered. The server URL can also be the reason: the Willow card uses https://api.planhat.com/v1/mcp, and Planhat's demo tenants (ws.planhatdemo.com) use a different host, https://api.planhatdemo.com/v1/mcp.

Solution: Check that you pasted the Client ID (not the secret) from the same Planhat tenant. For a demo tenant, add the server as a custom MCP server with the demo URL instead.

"Invalid redirect_uri: not registered for this client."​

Cause: The Willow redirect URL isn't in the OAuth Client's Redirect URLs field.

Solution: Copy the redirect URL from the Willow setup step and paste it into the OAuth Client in Planhat. Don't retype it, since it has to match exactly.

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

Cause: The OAuth Client's Permissions tab has no data model permissions enabled. Planhat doesn't accept it blank.

Solution: Enable at least one data model permission and click Save.

The agent can't see a model, field or record a user can see in Planhat​

Cause: Access is the overlap of the OAuth Client's permissions and the user's Role, so something the OAuth Client doesn't allow stays hidden.

Solution: Add the permission to the OAuth Client's Permissions tab and save. Then click Update connections in the client to push it to existing connections. Planhat says this can take up to an hour. Users who connected with dynamic permissions can edit them in their Planhat profile under Applications.

Tool calls return 401, 403 or 429​

Cause: Planhat returns 401 for a missing or invalid token, 403 when the app lacks permission for the call, and 429 when you hit a rate limit.

Solution: For 401, reconnect the server. For 403, update the OAuth Client's permissions. For 429, retry after the delay in the Retry-After header.

Additional Resources​

On this page