How to Build a Connector and Plugin for ChatGPT and Claude, Part 1: Plan Before You Code
A simple guide to planning an AI connector: map the conversation, design a few clear tools, choose how users sign in and decide where a widget helps.
About this series
In our previous post we explained what connectors, plugins and widgets are. Now let’s build one. This series has three short parts:
- Plan before you code (this post)
- Build the MCP server, tools and widget
- Secure, test and publish on ChatGPT and Claude
Throughout the series we use one simple example: a restaurant booking app that lets users find a restaurant and book a table right inside the chat.
Quick recap: the building blocks
| Piece | What it is | In our example |
|---|---|---|
| MCP server | A small web service that speaks the Model Context Protocol | https://mcp.example.com/mcp |
| Tools | Actions the AI can call | search_restaurants, book_table |
| Tool descriptions | Short text on each tool that tells the AI what it does and when to use it | “Find restaurants with free tables…” |
| Widget | An interactive HTML panel shown inside the chat | A card list with time slots and a “Book” button |
| Connector | Your MCP server, added to ChatGPT or Claude | “Table Booking” in the user’s connectors |
| Skills | Written guides that teach the AI a whole task, step by step | “How to book a table” |
| Plugin | The connector plus skills and branding in one installable package | The “Table Booking” plugin |
The good news: one MCP server works with both ChatGPT and Claude.
Tool descriptions vs. skills: who tells the AI what?
The AI can’t read your code. Everything it knows about your app comes from text you write, in three places:
| Guidance | Where it lives | What it answers | Example |
|---|---|---|---|
| Tool description | On each tool, in the MCP server | What does this one tool do, when should I call it and what do I pass? | “Find restaurants with free tables. Use when the user wants to eat out. Ask for the city, date, time and party size if missing.” |
| Server instructions | Once, in the MCP server | How do the tools fit together? | “Flow: search → user picks a time → book → deposit → confirmation.” |
| Skill | A Markdown file in the plugin | How do I do the whole task well, step by step, in the right tone? | “1. Ask only for missing details. 2. Search. 3. Let the user pick in the widget…” |
A simple way to remember it:
- Tool descriptions are labels on the buttons. They travel with the connector, so every client sees them.
- Skills are the training manual. They come with the plugin and teach the AI the best way to use those buttons together.
A connector works with tool descriptions alone. Skills make it work well, with fewer wrong turns and a better conversation. We write tool descriptions in Part 2 and skills in Part 3.
Step 1: Write the conversation first
Before thinking about code, write the shortest chat that gets the job done:
User: Book a table for four at an Italian place near me tomorrow at 8 pm. Assistant: Here are three options. (a widget shows restaurant cards with free time slots) User: (taps 8:00 pm at Trattoria Roma, enters a name and email, and pays a small deposit on the restaurant’s payment page) Assistant: You’re booked! A confirmation has been sent to your email.
Then list the stages the user passes through:
searching → choosing a slot → confirming details → paying the deposit → booked
Two simple rules make everything easier later:
- Every stage has a status the AI can check. The AI only knows what your tools tell it.
- Every stage has a way forward. If the user is waiting on something (an email, a payment), give them a button or a tool to check again.
Step 2: Design a few clear tools
Tools are the API the AI model sees. Design them around what the user wants to do, not around your database tables.
| Tool | Purpose |
|---|---|
search_restaurants(city, date, time, partySize, cuisine?) |
Find matching restaurants with free slots |
book_table(restaurantId, date, time, partySize, name, email) |
Hold the table and return a deposit payment link |
get_booking(bookingId) |
Check the status; the only tool that confirms the deposit is paid and the table is booked |
cancel_booking(bookingId) |
Cancel it |
Tips that save a lot of trouble:
- Keep the list short. Four clear tools beat fifteen overlapping ones; the model picks better.
- Use clear names and verbs.
book_tableis better thancreate_reservation_entity. - One tool is the source of truth. Only
get_bookingsays whether a booking is confirmed, so the AI never guesses. - Return a next step. Each result should hint at what to do next, such as “Ask the user which time they prefer, then call book_table”.
- Make repeat calls safe. Calling
book_tabletwice by accident shouldn’t create two bookings.
Step 3: Decide how users are identified
| Option | How it works | Choose it when |
|---|---|---|
| No sign-in | Tools work without an account (search, public info) | The data is public |
| Light identity | The user gives an email; you send confirmations there | One-off tasks, first-time users |
| OAuth sign-in | The AI client sends the user through your login once | Users have accounts and private data |
Start with the lightest option that is still safe. You can always add OAuth later.
Step 4: Decide where a widget helps
Not every step needs a UI. A good rule:
- Text is enough for questions, short answers and confirmations.
- A widget is better when the user needs to see or pick: comparing options, choosing a time slot, filling a form, uploading a file, watching progress.
Also plan a text-only fallback. Some clients or settings won’t show your widget, so every step should still work with plain text and links.
Step 5: Know the client differences
ChatGPT and Claude both support MCP connectors and interactive widgets, but a few details differ, for example how attached files are passed to tools and which extra widget features are available. The safe approach:
- Build on the open MCP standard first.
- Add client-specific extras only where they clearly help.
- Keep sensitive steps, like payments and passwords, on your own website, never inside the chat.
Step 6: Keep the connector thin
Don’t rebuild your product inside the connector. Let it call the services you already have:
ChatGPT / Claude ──► MCP server (new, small) ──► Your existing API, database, payments
This keeps business rules in one place and makes the connector quick to build and easy to maintain.
Planning checklist
- The conversation written from start to finish
- A status for every stage, and a way forward from each one
- 3–6 tools with clear names and one-line purposes
- A rough list of the skills your plugin will need (for example “get started” and “book a table”)
- An identity choice (none, email or OAuth)
- Widget screens listed, each with a text fallback
- Sensitive steps kept on your website
Next up
In Part 2: Build the MCP Server, Tools and Widget we turn this plan into a working MCP server with tools and an interactive widget.