Skip to content

Planfix MCP

MCP (Model Context Protocol) allows AI assistants and other compatible applications to work with Planfix data through a standard protocol.

After a connection is established, the client receives only the explicitly allowed capabilities and acts on behalf of the employee who signed in. Standard Planfix access permissions still apply: an AI assistant cannot view or change anything that is not available to that user.

The available actions depend on the MCP client, the granted permissions, and the current server version. For example, a client may be able to find tasks and contacts, read their details, and add comments when the corresponding permissions are granted.

Requirements

  • a Planfix employee account;
  • an MCP client that supports Streamable HTTP and OAuth.

MCP server address

Use this MCP server URL: 

https://mcp.planfix.com/mcp

The URL is the same for every Planfix account. Do not add an account name to it or send a separate account header. The account is selected during OAuth authorization.

Connecting any MCP client

  1. Open the MCP server settings in the client.
  2. Add a new server using the Streamable HTTP transport.
  3. Enter a name such as Planfix and the MCP URL.
  4. Save the settings and start OAuth authentication.
  5. In the browser window that opens, select your Planfix account. You can find it by name, URL, or email address.
  6. Check the application name and requested permissions, and then confirm the connection.

If the application has not yet been allowed in the account, Planfix will indicate that administrator approval is required. An account administrator or technical administrator can approve the application. If the administrator is also the person connecting it, they can approve and connect it in one action.

For a DCR connection of Codex, the request cannot be forwarded to an administrator after sign-in starts, so choose the appropriate scenario from the next section in advance.

Connecting Codex

Choose the option depending on whether you are an administrator of the account to be connected.

If you are an administrator: connect via DCR

This option is available to the account administrator or the technical administrator. During sign-in they will be able to both approve the automatically registered application and connect it.

Add the MCP server: 

codex mcp add planfix --url https://mcp.planfix.com/mcp

Start OAuth sign-in and explicitly choose DCR as the client registration method: 

codex mcp login planfix --oauth-client-registration dcr

Codex will open the browser. Select the Planfix account in which you are an administrator, check the requested permissions and click Allow and connect.

An application registered via DCR always requires explicit approval by the account. A regular employee should not start this scenario: currently a DCR connection request cannot be deferred and forwarded to an administrator for separate approval.

The --oauth-client-registration dcr parameter applies only to this sign-in and is not saved to config.toml. Codex will store the received OAuth connection data itself.

If you are not an administrator: connect using client_id

First ask the account administrator or the technical administrator to create an application:

  1. Open Account management → API → OAuth and MCP applications.
  2. In the Applications of this account block click Create application.
  3. Enter a name, for example Codex.
  4. Choose type Public client. A client secret is not required for Codex.
  5. Add Redirect URI http://127.0.0.1/callback.
  6. Select the minimally required permissions and save the application.
  7. Give the obtained client_id to the user.

Planfix publishes the issuer and supports binding the authorization response to it, so a new pre-registered Codex client uses the stable callback http://127.0.0.1/callback. During sign-in Codex adds a temporary loopback port; Planfix accepts such a port if the host and path remain unchanged.

The user adds the server, substituting the issued identifier: 

codex mcp add planfix --url https://mcp.planfix.com/mcp --oauth-client-id CLIENT_ID

Codex will show the full callback URL. In the default configuration it looks like this: 

OAuth callback URL: http://127.0.0.1/callback

If another address is shown due to custom Codex settings, ask the administrator to add that Redirect URI to the application.

Then run: 

codex mcp login planfix

Providing --oauth-client-id means Codex will use the pre-registered client and will not start CIMD or DCR. Settings are saved approximately like this: 

[mcp_servers.planfix]
url = "https://mcp.planfix.com/mcp"

[mcp_servers.planfix.oauth]
client_id = "CLIENT_ID"
callback_url = "http://127.0.0.1/callback"

Codex app and IDE extension

The Codex app, Codex CLI and the IDE extension use a shared MCP configuration on the same computer. After the first connection via the CLI restart the app or the extension. The server will appear in Settings → MCP servers. If Authenticate is displayed next to it, click that button and complete sign-in.

You can check active MCP servers with the command /mcp in the Codex input field.

List and status of connections can be viewed with: 

codex mcp list

Current UI elements, commands and callback selection rules are described in the official OpenAI MCP documentation.

If another MCP client cannot register automatically

A modern MCP client can register automatically via CIMD or DCR. Such registration does not by itself grant access to the account: account rules and administrator approval remain in effect.

If the client requires a pre-defined client_id, ask the administrator to create a public application for the account:

  1. Open Account management → API → OAuth and MCP applications.
  2. In the Applications of this account block create an application.
  3. Choose type Public client.
  4. Add the Redirect URI shown by the MCP client.
  5. Select the minimally required permissions.
  6. Give the obtained client_id to the user or add it to the client settings.

Such an application will be able to connect only to the account that created it. Details — in article OAuth and MCP applications in an account.

Multiple accounts

Each connection is associated with one account and one user.

  • For a DCR connection add another MCP server under a different name and during sign-in choose another account in which you have administrator rights.
  • An account-owned application and its client_id work only in the account that created them. For another account its administrator must create a separate public application; add it to Codex under a different name with the new client_id.

Do not change the MCP URL and do not add the account name to requests. The server determines the account by the issued OAuth token.

Disconnecting MCP

To revoke your connection:

  1. Open your user card in Planfix.
  2. Go to Session management.
  3. Find the application marked MCP and delete the session.
  4. Remove or disable the server in the MCP client if you no longer need it.

Deleting the session revokes the associated OAuth tokens. Connecting again requires a new sign-in and consent.

An administrator can revoke an application for the entire account under Account management → API → OAuth and MCP applications.

Security

  • Connect only applications you trust.
  • Before approval, verify the application name, owner, redirect URI, and requested permissions.
  • Grant the minimum permissions required. Do not grant modification or deletion permissions for a read-only use case.
  • Never paste an access token or refresh token into a chat, request settings, or logs.
  • Remember that task, contact, and comment content may be sent to an external AI service according to that service's data processing terms.
  • Remove a connection from Session management if it is no longer used or you do not recognize it.

Troubleshooting

If DCR sign-in requires administrator approval, sign in as the account administrator or technical administrator and click Allow and connect. A regular employee cannot forward a started DCR request for separate approval.

Message or symptom What to do
The application is blocked by the account policy An administrator must approve the specific application or change the third-party application policy.
The client asks for authorization again after sign-in Remove the connection from the client and create it again. Make sure the exact MCP URL is being used.
The wrong account was selected Revoke the connection and sign in again, selecting the correct account. A token cannot be switched to another account.
The client requests a client_id Ask the administrator to create a public application for the account and add the MCP server with the --oauth-client-id parameter.
An operation is unavailable Check the granted scopes and the user's own access permissions in Planfix.

Go To

Retrieved from "https://planfix.com/help/Planfix_MCP"