AIMCPConnectorsAditya Uke

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:

  1. Plan before you code (this post)
  2. Build the MCP server, tools and widget
  3. 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_table is better than create_reservation_entity.
  • One tool is the source of truth. Only get_booking says 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_table twice 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.

More on this topic:AIMCPConnectors