Planfix MCP

From Planfix

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.

Connecting Codex

Recommended: connect through CIMD

On planfix.com, Codex automatically selects CIMD. An administrator approves the CIMD application in the account once, and employees can then complete their own OAuth sign-in without another application approval. For this method, you do not need to create an application manually, provide a client_id, add a redirect URI, or store a client secret.

For the first connection, an account administrator or technical administrator runs: 

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

Codex opens a browser. Select a Planfix account where you are an administrator, review the requested permissions, and select Approve and connect. The CIMD application needs this approval only once in that account.

Afterward, each employee who needs access runs the same commands: 

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

The employee signs in with their own Planfix account and confirms their own access. The administrator does not need to approve the CIMD application again.

Alternative: use an account-owned application

Use this method when you need a predefined OAuth client managed by the account, with a permanent client_id, or when CIMD cannot be used in your configuration.

An account administrator or technical administrator creates the application:

  1. Open Account management → API → OAuth and MCP applications.
  2. Under Applications owned by this account, select Create application.
  3. Enter a name such as Codex.
  4. Select Public client. Codex does not need a client secret.
  5. Add http://127.0.0.1/callback as a redirect URI.
  6. Select the minimum required permissions and save the application.
  7. Give the generated client_id to the employees who will connect.

Planfix publishes an issuer and supports issuer-bound authorization responses, so a newly added pre-registered Codex client uses the stable http://127.0.0.1/callback callback. Codex inserts a temporary loopback port during sign-in, and Planfix accepts that port when the host and path remain unchanged.

Each user adds the server using the provided ID and signs in: 

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

Codex displays the complete callback URL. With the standard configuration, it is: 

OAuth callback URL: http://127.0.0.1/callback

If Codex displays a different address because of a custom callback setting, ask the administrator to add that exact redirect URI to the application.

Providing --oauth-client-id tells Codex to use the pre-registered client and skip CIMD and DCR. The saved configuration is similar to: 

[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"

When sign-in starts, Planfix opens the account that owns the application. Review the permissions and confirm the connection.

Codex app and IDE extension

The Codex app, Codex CLI, and IDE extension share MCP configuration on the same computer. After the initial CLI setup, restart the app or extension. The server appears under Settings → MCP servers. If it displays Authenticate, select it and complete sign-in.

Enter /mcp in the Codex composer to view active MCP servers.

To view the configured servers and their status from the CLI, run: 

codex mcp list

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

Multiple accounts in Codex

Each connection is associated with one account and one user.

With CIMD, an administrator must approve the application once in every account you want to connect. Add each connection under a different name and select the required account during OAuth sign-in. If you use account-owned applications instead, each account needs its own application and client_id.

Do not change the MCP URL or add an account name to requests. The server determines the account from the OAuth token.

Troubleshooting Codex connections

If administrator approval is required during the first CIMD sign-in, complete the connection as an account administrator or technical administrator and select Approve and connect. Employees can sign in on their own after the application has been approved.

If CIMD cannot be used and Codex requests a client_id, use the alternative account-owned application method described above.

Other MCP clients without automatic registration

Modern MCP clients can register automatically through CIMD or DCR. Automatic registration does not grant account access by itself: the account policy and administrator approval still apply.

If another client requires a predefined client_id, ask an administrator to create a public account-owned application:

  1. Open Account management → API → OAuth and MCP applications.
  2. In Applications owned by this account, create an application.
  3. Select Public client.
  4. Add the redirect URI shown by the MCP client.
  5. Select the minimum required permissions.
  6. Provide the generated client_id to the user or add it to the client settings.

The application can connect only to the account that created it. See OAuth and MCP applications in an account for details.

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

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.
An operation is unavailable Check the granted scopes and the user's own access permissions in Planfix.

Go To