> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/installation-and-setup/chatgpt-desktop.md).

# ChatGPT Desktop

Connect the [ChatGPT desktop app](https://learn.chatgpt.com/docs/extend/mcp) to BalkanID MCP.

**OAuth is preferred.** The app can also use a Bearer API key when you need Read-only access or OAuth is unavailable.

This guide is for the **desktop app**. For ChatGPT **web** custom connectors, see ChatGPT. The desktop app shares MCP configuration with the Codex CLI and IDE extension — if you already added BalkanID via `codex mcp add`, it may already appear under **Plugins → MCPs**.

### One-click (OAuth — recommended)

1. Open <https://mcp.balkanid.app>, sign in, and confirm the correct **tenant**.
2. Under **OAuth Connectors**, select **ChatGPT Desktop**.
3. In the ChatGPT desktop app, open **Plugins** → **MCPs** → **Add** (or **Connect a custom MCP**).
4. Set **Name:** `balkanid` · **Type:** **Streamable HTTP** · **URL:** `https://mcp.balkanid.app/server/mcp` — leave token and header fields empty.
5. Click **Save**.
6. If the UI shows **Authenticate** next to `balkanid`, click it. Your browser opens — sign in to BalkanID, select your **tenant**, and approve consent.

{% hint style="info" %}
OAuth currently requires **both Read and Write** scopes. See Authentication and Permissions.
{% endhint %}

### Manual configuration (OAuth fallback)

1. **Plugins** → **MCPs** → **Add** → custom MCP.
2. **Name:** `balkanid` · **Type:** Streamable HTTP · **URL:** `https://mcp.balkanid.app/server/mcp` · leave token and header fields empty.
3. **Save**, then **Authenticate** when prompted and complete BalkanID OAuth.

### One-click (API key)

1. In the [MCP UI](https://mcp.balkanid.app), create a key under **Bearer Auth Keys**.
2. Open **Connect** for that key, choose **ChatGPT Desktop**, and copy the environment variable name (for example `BALKANID_MCP_TOKEN`) and the token value.
3. Set the variable in the environment that launches ChatGPT, then add or edit `balkanid` in **Plugins** → **MCPs** with **Bearer token env var** set to the variable's name.
4. **Save** and restart the ChatGPT desktop app so it inherits the environment.

### Manual configuration (API key fallback)

1. Create an API key in the [MCP UI](https://mcp.balkanid.app) under **Bearer Auth Keys**.
2. Choose an environment variable name and set the **actual token** in the process environment that launches ChatGPT — not in the URL field.
3. In **Plugins** → **MCPs**, add or edit `balkanid`: **Type:** Streamable HTTP · **URL:** `https://mcp.balkanid.app/server/mcp` · **Bearer token env var:** the variable's name only.
4. **Save** and restart the app.

Do not commit tokens. Rotate keys from the MCP UI if exposed.

### Verify

Ask ChatGPT: “Call whoami on BalkanID MCP.” You should see your email and tenant ID.

### Disable or remove

In **Plugins → MCPs**, under **Servers**:

* **Disable:** turn off the toggle next to `balkanid`. Its setup is kept; turn the toggle back on to re-enable it.
* **Edit:** select the gear icon to open **Update Balkanid MCP**, change the URL, token variable, or headers, then select **Save**.
* **Remove:** select the gear icon, then select **Uninstall** at the top right.

To switch the server type (for example, from Streamable HTTP to STDIO), uninstall it first, then add it again. Changes also apply to the Codex CLI and IDE extension, since they share the same configuration.

### Official documentation

OpenAI documentation for MCP in the ChatGPT desktop app:

* [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp) — ChatGPT Learn


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/balkanid-mcp/installation-and-setup/chatgpt-desktop.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.