$cat connect/chatgpt.md

Connect ChatGPT.

OAuth · PAT

Give ChatGPT — including Codex and the OpenAI Responses API — a live connection to your markdown workspace over the Model Context Protocol. It can read your documents, use folder descriptions as context, and create, update, and organise notes — instead of you re-pasting the same background into every chat.

Two ways to authenticate, both covered here:

›OAuth sign-in — the easiest path for the ChatGPT app connector. Paste one URL and sign in; there is no token to create or copy.
›Personal Access Token (PAT) — for Codex, the OpenAI Responses API, and custom GPT Actions, which send their own credential.

Both require an MDflow Pro account — all API and MCP access is Pro-gated. OAuth is currently in beta; the token path is a fully supported fallback everywhere.

$which chatgpt

Which surface are you connecting?

Field	What to enter
ChatGPT app (connector)	Use OAuth — add a custom connector and sign in. See Method A.
Codex (CLI / IDE)	Runs MDflow's local MCP server with a PAT. See Method B.
OpenAI Responses API	Pass the hosted server as a remote MCP tool with a PAT header. See Method C.
Custom GPT (GPT builder)	Uses Actions against MDflow's REST API with a static OAuth client. See Method D.

$open https://mdflow.cz/api/mcp

Method A — OAuth sign-in (ChatGPT connector)

ChatGPT's connector picker speaks the same MCP + OAuth 2.1 flow as Claude and registers itself automatically (Dynamic Client Registration), so connecting is paste a URL and sign in — no token, no client ID or secret. Custom MCP connectors are available to Plus, Pro, Business, Enterprise, and Edu accounts; you may need to enable developer mode first.

1Paste MCP URL in ChatGPT

2Client discovers MDflow & self-registers

3Sign in to MDflow

4Approve consent screen

5Connected — tools appear

Open the connector settings

In ChatGPT, open Settings → Connectors. If custom MCP servers aren't shown, enable Settings → Connectors → Advanced → Developer mode. Then Add a new connector.

Fill in the connector

Authentication is detected as OAuth — there is no client ID or secret to enter.

Field	What to enter
Name	Anything, e.g. `MDflow`
MCP server URL	`https://mdflow.cz/api/mcp`
Authentication	OAuth (auto-detected) — no client ID / secret

ChatGPT — Add connector

Name

MDflow

MCP server URL

https://mdflow.cz/api/mcp

Authentication: OAuth — detected automatically

CancelCreate

Illustration — the Add connector dialog.

Sign in and approve

ChatGPT sends you to MDflow. Sign in if needed, then review and Approve the consent screen. The MDflow tools appear in the connector.

mdflow.cz/oauth/consent

Authorize ChatGPT

ChatGPT wants to connect to your MDflow account.

This will allow ChatGPT to:

•Confirm your identity
•See your email address
•See your name and avatar
•Full access to read and modify your MDflow documents (Pro plan required for API access).

DenyApprove

Illustration — MDflow's consent screen, the one step every sign-in passes through. Click Approve to finish connecting.

Known limitation (beta): Some ChatGPT surfaces prefer Client ID Metadata Documents (CIMD), which MDflow's OAuth server does not yet ship. MDflow advertises Dynamic Client Registration, which ChatGPT connectors also support, so the DCR path normally engages. If a particular ChatGPT surface refuses to connect via OAuth, use a Personal Access Token for that surface for now (Methods B and C).

Under the hood: A tokenless request to /api/mcp returns 401 with a WWW-Authenticate challenge pointing at /.well-known/oauth-protected-resource(RFC 9728). ChatGPT discovers the authorization server, registers itself, runs the OAuth 2.1 authorization-code + PKCE flow through MDflow's consent page, and calls the API with the issued JWT.

$edit ~/.codex/config.toml

Method B — Codex

Codex launches MCP servers it finds in ~/.codex/config.toml. Point it at MDflow's local stdio server and pass a Personal Access Token through the environment.

Create a Personal Access Token

Download the local server

Grab server.mjs and run npm install — the full download and prerequisites (Node.js 18+) are in the MCP documentation.

Add the server to config.toml

Use the absolute path to server.mjs (run pwd in the mdflow-mcp folder to get it).

Codex~/.codex/config.toml

$toml

[mcp_servers.mdflow]
command = "node"
args = ["/absolute/path/to/mdflow-mcp/server.mjs"]
env = { MDFLOW_API_TOKEN = "mdf_your_token_here" }

Restart Codex and try it

Restart so it picks up the config, then ask:

>Get information about onboarding from mdflow.

>Use mdflow to get context about my API documentation.

Security: The token lives only in your config's envblock, never in a chat prompt or tool argument — MDflow's server refuses to accept it as a tool parameter. Tokens grant workspace-level access, including write and delete, and can be revoked anytime from Settings.

$POST /v1/responses

Method C — OpenAI Responses API

Wiring a ChatGPT-family model to MDflow programmatically? Pass the hosted server as a remote mcp tool with a headers object carrying your Personal Access Token. No local server needed — the request reaches https://mdflow.cz/api/mcp directly.

OpenAI Responses APIPOST https://api.openai.com/v1/responses — remote MCP tool

$json

{
  "model": "gpt-5.2",
  "tools": [
    {
      "type": "mcp",
      "server_label": "mdflow",
      "server_url": "https://mdflow.cz/api/mcp",
      "headers": { "Authorization": "Bearer mdf_your_token_here" }
    }
  ],
  "input": "Get information about onboarding from mdflow."
}

The server is stateless with a 30-requests-per-minute limit per token; 429 responses carry Retry-After in seconds. The same operations are available as a plain HTTP API with the same token.

$gpt-builder → actions

Method D — Custom GPT Actions (advanced)

The classic GPT builder does not speak MCP or automatic registration — it needs a static OAuth clientand the endpoint URLs typed in by hand. This path is only for building a custom GPT against MDflow's REST API; most people want Method A.

One-time operator step: An MDflow / Supabase admin must first create a confidential OAuth client in the Supabase dashboard under Authentication → OAuth Apps → Add client (type confidential, token_endpoint_auth_method: client_secret_post). After you save the GPT's auth config, copy the callback URL the GPT builder generates (https://chat.openai.com/aip/g-<your-gpt-id>/oauth/callback) back into the OAuth App's redirect URIs — no wildcards allowed.

In the GPT builder, open Configure → Actions → Authentication and fill in:

Field	What to enter
Schema / Import URL	`https://mdflow.cz/openapi.json`
Authentication type	OAuth
Client ID / Secret	From the Supabase OAuth App above
Authorization URL	`https://avpohqkozlquuxzqqtsx.supabase.co/auth/v1/oauth/authorize`
Token URL	`https://avpohqkozlquuxzqqtsx.supabase.co/auth/v1/oauth/token`
Scope	`openid email profile`
Token exchange method	Default (POST)

After saving, copy the callback URL ChatGPT shows you back into the Supabase OAuth App's redirect URIs to complete the two-step handshake. avpohqkozlquuxzqqtsxis MDflow's public Supabase project ref — not a secret.

$man troubleshooting

Troubleshooting

ChatGPT connection troubleshooting: symptoms and fixes
Symptom	Cause & fix
ChatGPT won't connect via OAuth	Likely the CIMD preference (see the beta note above). Use a Personal Access Token via Codex or the Responses API for that surface for now.
Custom MCP connectors don't appear	Enable Developer mode under `Settings → Connectors → Advanced`. Custom connectors need a Plus, Pro, Business, Enterprise, or Edu account.
`403 Pro plan required` after connecting	The signed-in account is on the Free plan. Upgrade at Settings — the connection stays, calls start working.

./mcp — full MCP reference →./claude — connect Claude instead →

> Connect ChatGPT.