Connect TeamGrid to ChatGPT

Use this guide for the hosted MCP server, stable release 1.2.2. You do not need to install Node.js, the CLI or a local MCP process for this connection.

Before you connect

You need a TeamGrid account with membership in the intended workspace. Your TeamGrid role must permit the operations you request. Sensitive scopes require a Passkey registered on that account; confirm it personally when prompted.

Your ChatGPT account and workspace policy must permit custom MCP connections. Developer mode availability and menu labels are controlled by OpenAI. These steps follow the current OpenAI connection guide, reviewed on 2 October 2026. If the option is unavailable, ask your ChatGPT workspace administrator to check its policy.

1. Choose the regional endpoint

Choose the region that owns the workspace, not the country where you are working. The regional routing guide explains how to identify it. Include the /mcp path. A workspace website, API v1 URL or browser consent URL is not an MCP endpoint. One authorized connection belongs to one workspace.

2. Add the connection

1. In ChatGPT, open Settings → Security and login → Developer mode.
2. Open ChatGPT Plugins, select the plus button and add a custom MCP connection.
3. Name it clearly, for example TeamGrid · Acme · DE, and enter the URL above.
4. Select OAuth authentication and complete the connection flow. TeamGrid uses client metadata discovery and public-client PKCE; there is no TeamGrid client secret or API token to paste into this setup.
5. Sign in on TeamGrid, choose the intended workspace and inspect the requested permissions before choosing Allow access / Zugriff erlauben.

The hosted server advertises the full catalog. It can request additional scopes for a later operation through incremental consent. Tool visibility alone does not mean you have permission to execute that tool. CLI flags such as --tool-profile do not configure this hosted connection.

3. Complete TeamGrid consent

Check the client name, workspace and scopes on every consent screen. If sensitive permissions are requested, a confirmation window opens for your personal Passkey. After successful confirmation it closes and the connection flow continues. A request containing only ordinary read scopes can complete without that popup.

Your Passkey belongs to your TeamGrid account. Confirmation can open the central login.teamgrid.app page even for a US workspace; another workspace-specific Passkey is not required. See account and region confirmation if the popup reports that the request is unavailable for your account.

Who chooses the permissions?

The MCP client requests OAuth scopes; TeamGrid displays the requested set for the workspace you choose. The current consent screen lets you approve or deny that set. It does not provide individual scope checkboxes or add permissions that the client has not requested.

The initial connection requests workspace:read. This identifies your workspace; it does not authorize reading all its business data or writing to it. A later operation can require additional consent:

An operation with protected fields or related resources can require additional scopes. Check its tool reference and the actual consent screen. Existing approved scopes should be retained when requesting additional access. You can decline a new request; previously approved reads remain available while their original connection is valid. TeamGrid roles, sharing rules and workspace locks apply independently of OAuth consent.

If you need a specific scope set at initial setup in a local MCP client, use the CLI browser-login workflow and an explicit tool profile. That local configuration does not change the hosted ChatGPT connection.

Do not dismiss a generic connection failure as a browser or cookie problem. If the request expires, restart the connection from ChatGPT. Refreshing an expired consent URL cannot create a new request. The OAuth troubleshooting matrix covers sign-in sessions, permissions, expired requests and popup failures.

4. Verify the workspace with a read

Start a new conversation with the TeamGrid connection enabled and ask:

Call teamgrid_workspace_get once with {}. Show the workspace name and ID, region and cell. Do not read another resource or make a change.

Compare the result with the workspace you selected. Then try a bounded read:

List at most five non-archived projects with teamgrid_projects_list. Do not request another page. Use only the returned TeamGrid data.

The second request needs projects:read in addition to workspace access. Review any additional consent. For the exact arguments, use the project-list reference.

5. Use write tools deliberately

Writes are available in Production DE and US. They require current scopes and TeamGrid permissions, a confirmed workspaceId, and the operation’s declared revision or idempotency key. Follow the complete task-write walkthrough before changing an important resource.

Ask ChatGPT to read the target, show the proposed change and wait for your approval. Review the actual target and arguments in the host confirmation. Afterwards, inspect meta.outcome and verify the resource. Acceptance of a job is not completion. Tool safety annotations guide the host; they do not replace TeamGrid authorization.

Update, disconnect and reconnect

If ChatGPT has cached an earlier tool catalog, open its connection settings and select Refresh, then start a new conversation. If authentication is invalid, reconnect and review TeamGrid consent again.

Access tokens currently last up to five minutes. The host renews them using the refresh token while the underlying grant remains valid. This renewal does not add permissions and should not require a new login every few minutes. An additional-permission request is separate from token expiry. If ChatGPT says the connection has expired immediately before a new read or write, the message alone does not establish the cause: check the approved scopes and see early reconnect prompts.

Removing a connection from ChatGPT stops its use in that host. To revoke its server-side token family, open the owning TeamGrid workspace’s Settings → Team → Developer Center → Access, find the connected application and disconnect it. Closing a conversation or browser tab does not revoke access. Other workspace connections have their own grants.

What this connection supports

TeamGrid provides supervised business tools and private resources. It does not advertise standard search/fetch tools for ChatGPT company knowledge, embedded ChatGPT widgets or a published plugin-directory listing. teamgrid_search is a bounded TeamGrid business search. See protocol support and limits.

For another OAuth client, TeamGrid must approve that client’s exact metadata and redirect requirements. The supported registration method is documented under remote OAuth configuration.