A hands on tutorial for adding a custom MCP server to ChatGPT. Switch on developer mode, fill in the connector form, choose OAuth or no authentication, test the server with a tunnel, fix the common errors, and add image and video tools.
You have a server that does something useful, and you want ChatGPT to call it from an ordinary chat. The door exists, and it is a single form. The catch is that the form hides four or five traps that make a perfectly healthy server look broken. This tutorial runs the whole path, from switching on developer mode to approving the first tool call, and it flags each trap before you step on it. You will build a tiny test server, expose it with a tunnel, fix the errors people hit most, and then see how image and video tools from PicassoIA can plug into the same connector.
The Model Context Protocol (MCP) is an open standard that lets an AI client call tools on a server. The server publishes a list of tools. Each tool has a name, a plain-English description and a JSON schema for its inputs. The client reads that list, decides when a tool helps, and sends a structured request. The server answers with data or performs an action.
In ChatGPT, a custom MCP connector is the settings entry that points ChatGPT at one of those servers. Once it is saved, your tools appear in chats next to the built-in ones.
Built-in connectors handle popular apps. Your own server handles everything else:
💡 Remote only. ChatGPT talks to remote MCP servers. A server that runs as a local process over stdio, the way many desktop tools do, has to be wrapped in an HTTP endpoint before ChatGPT can reach it.
Developer mode began as a beta for Plus and Pro accounts on the web. Workspace plans such as Business, Enterprise and Edu reach it through an admin-controlled permission instead of a personal toggle. OpenAI has adjusted which plans get write actions, and has moved the switch between menus more than once, so treat any plan list (including this one) as a moving target. If your screen differs from the steps below, check OpenAI's current help article on developer mode.
In a workspace, the permission usually sits in the permissions and roles area of workspace settings. If the switch is missing for you, ask an admin before blaming your server.
ChatGPT connects from OpenAI's infrastructure, not from your laptop. That has three consequences:
ChatGPT accepts two remote transports:
| Transport | Works with ChatGPT | Typical URL | Notes |
|---|---|---|---|
| Streamable HTTP | Yes | https://your-domain.com/mcp | Best choice for a new server |
| SSE (Server-Sent Events) | Yes | https://your-domain.com/sse | Older style, still accepted |
| stdio (local process) | No | none | Wrap it in an HTTP server first |
Custom connectors sit behind a switch, because a custom server can read and change real data. Here is the path:
Once the switch is on, a Create button appears on the connectors page.
💡 Can't find the switch? The setting has moved during 2026. Search the settings window for the word "developer" before you decide your plan lacks it.
Click Create and fill in these fields:
| Field | What to enter | Tip |
|---|---|---|
| Name | A short label such as "Order Lookup" | This is what you pick in the chat menu |
| Description | One or two sentences about what the server does | The model reads it when deciding whether to call a tool, so write it like an instruction |
| Icon | Optional | Helps you spot it in a long list |
| MCP server URL | The full HTTPS URL including the path, such as https://api.example.com/mcp | A missing path is a very common cause of failure |
| Authentication | No authentication or OAuth | Details in the next section |
Tick the checkbox confirming that you trust the application, then click Create.
| Option | Use it when | Risk |
|---|---|---|
| No authentication | Public, read-only data, or a throwaway test server | Anyone who finds the URL can call your tools |
| OAuth | Anything tied to a user account, private data or write actions | You must run or connect an OAuth provider |
With OAuth, ChatGPT sends you to your identity provider's login page right after you click Create. Sign in, click allow, and you land back in ChatGPT with the connector authorized.
Whichever provider you use, ask for the narrowest permissions your tools need. A connector that only reads orders should never hold permission to refund them, because the permissions you grant are the ceiling on the damage a bad tool call can do.
Start with no authentication on a test server that returns harmless data. Move to OAuth before the server touches anything real.
For the first few tests, name the connector in your prompt: "Using Order Lookup, list my open orders." Naming it removes one variable. Once the tool works, drop the name and see whether ChatGPT picks it on its own, which tells you whether your description is doing its job.
💡 Read the confirmation card. In developer mode every tool call is shown to you before it runs. That card is your last checkpoint, so skim the arguments instead of clicking through.
A harmless tool is the fastest way to prove the connection works before you point ChatGPT at real data. This one counts words, using the official Python SDK:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-connector", stateless_http=True)
@mcp.tool()
def word_count(text: str) -> int:
"""Count the words in a block of text.
Use when the user asks how long a draft is."""
return len(text.split())
if __name__ == "__main__":
mcp.run(transport="streamable-http")
Four habits make a tool easy for a model to use:
lookup_order and refund_order beat a single manage_order.Install the SDK with pip install "mcp[cli]" and run the file. With the SDK defaults at the time of writing, the endpoint is http://127.0.0.1:8000/mcp. If your version uses another port or path, its docs will say so.
Before ChatGPT ever sees the server, point the MCP Inspector at it:
npx @modelcontextprotocol/inspector
Choose the Streamable HTTP transport, paste the local URL, connect, and list the tools. If word_count shows up and runs, the server is healthy and any later failure belongs to the network or the form.
A tunnel gives your local port a public HTTPS address:
ngrok http 8000
Cloudflare's cloudflared tunnel --url http://localhost:8000 does the same job. Copy the HTTPS address it prints, add /mcp, and paste that into the MCP server URL field.
💡 Free tunnel URLs rotate. Restart the tunnel and the address changes, which breaks the connector. Re-create it with the new URL, or move to a stable domain once the test works.
| Symptom | Likely cause | Fix |
|---|---|---|
| Connector fails to create | URL is HTTP, local, or behind a VPN | Use a public HTTPS address or a tunnel |
| Not found on connect | Wrong or missing path (/, /mcp, /sse) | Open the exact URL in the Inspector first |
| Connects but shows zero tools | The tool list request errors out | Read your server logs for the list request |
| OAuth login loops | Redirect address not allowed by the provider | Add the callback address your provider's setup page asks for |
| Tools never get called | Descriptions are vague | Say when to use each tool, and when not to |
| Worked yesterday, fails today | Tunnel address rotated | Re-create the connector with the new URL |
Debug in this order, and stop at the first step that fails. First, open the Inspector and connect to the exact URL. Second, request that URL from a terminal with curl and confirm it answers over HTTPS. Third, read your server logs while you click Create. Only then suspect ChatGPT or the form. Working from the server outward saves you from tweaking settings that were never broken.
You changed the tool list, but ChatGPT still shows the old one. Open the connector's settings and use the refresh option. If that does nothing, delete the connector and add it again, which forces a fresh read of the server.
One more detail worth knowing: OpenAI's documentation describes a search tool that returns candidate results and a fetch tool that returns one document by ID for features such as deep research. A server with only custom tools can work in developer mode yet stay invisible to those features.
Text your server returns becomes text the model reads. A support ticket, a web page or a shared document can carry hidden instructions meant to steer the model into calling a tool you never intended. OpenAI's own warning is blunt: watch for prompt injection and review every tool call, especially write actions.
Build with that in mind:
The most satisfying connectors produce something you can see. PicassoIA offers a developer API at https://api.picassoia.com/v1, authenticated with a bearer token that starts with pia_sk_. The endpoints follow the Replicate style: a POST to /v1/models/{owner}/{name}/predictions starts a job, and a GET on /v1/predictions/{id} polls it. Four models are available through the API and MCP:
Jobs are asynchronous, so build two tools instead of one: a starter that returns a prediction ID, and a checker that returns the output once the job finishes. ChatGPT can call the checker until the result is ready.
import os
import httpx
PIA = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_TOKEN']}"}
@mcp.tool()
def start_image(prompt: str) -> dict:
"""Start an image job. Returns an id to pass to get_result."""
r = httpx.post(
f"{PIA}/models/picassoia/picassoia-image/predictions",
headers=HEADERS, json={"input": {"prompt": prompt}}, timeout=30,
)
r.raise_for_status()
return {"id": r.json()["id"]}
@mcp.tool()
def get_result(prediction_id: str) -> dict:
"""Check a job. Returns status and, when finished, the output."""
r = httpx.get(f"{PIA}/predictions/{prediction_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
return {"status": data.get("status"), "output": data.get("output")}
Treat this as a sketch. The request body follows the Replicate convention, so confirm the exact input fields on the model page before you ship it.
Some limits shape the design. An account runs at most 5 predictions at once, and that count is shared across tokens and MCP connections. Prompts top out at 4,000 characters, and a single request body at 10 MB. Access terms and pricing live on the PicassoIA pricing page, so read them before promising anyone a free tier.
💡 Prefer not to host anything? PicassoIA also offers hosted MCP connections, managed at picassoia.com/en/mcp/accounts after you sign in. Check which clients a connection supports before you rely on it in ChatGPT.
Tool descriptions matter more than the code behind them, because the model picks tools by reading them. An LLM can sharpen yours in a few minutes:
For a second opinion on wording, paste the same material into Claude Sonnet 5 and compare the two rewrites. Keep whichever description is shorter and more specific.
Build the word counter first and watch that first tool call appear in a chat. Then give the connector something to show. Add the image starter, ask ChatGPT for a photo of an ordinary scene, and change one detail per request: the lens, the light, the time of day. Small edits teach you more about prompts than any long description does.
When you want finished pictures without writing a server, open PicassoIA and try creating your own images with PicassoIA Image, refine them with PicassoIA Image Editor Pro, and bring a favorite to life with PicassoIA Video. Pick one prompt, run it three ways, and keep the version that makes you look twice.
