DEV Community: Sheen

Hey Guys!! I am back again after a long break. Just published my latest post, show some love👀🤩

Sheen — Wed, 21 Oct 2026 12:40:07 +0000

How I Triage Release Notes Before Claude Code Turns Them Into a Product Video

Sheen — Wed, 21 Oct 2026 12:35:31 +0000

Ask an agent to make a video from CHANGELOG.md and it will often treat every line as content, including the dependency bump. Nothing looks wrong until the render, where the React upgrade has six seconds of screen time.

I would rather argue about a cut list than about a finished video. So I wrote a small script that sorts a changelog into keep, cut and "a human should look" before the agent sees it. The sorting turned out to be the boring part. The rows the script refuses to decide are the interesting ones.

Why the raw changelog is a bad input

A changelog is written for the team that shipped the release. It records what happened, in the order a maintainer thinks about it, and nothing in the file says which entries a customer cares about.

That leaves an agent two ways to go wrong. The first is coverage: it can treat every line as content. The second is confidence: when a line is thin, a model tends to fill the gap with a stronger headline than the line supports. A fix for one crash turns into "crashes are gone". Both mistakes are cheap to catch in a table and expensive to catch in a render.

The script

It reads a changelog in the Keep a Changelog layout, takes the newest dated release, and prints a verdict for every entry. It uses only the standard library.

#!/usr/bin/env python3
"""Draft a keep/cut table for the newest dated release in a CHANGELOG.md."""
import argparse
import re
import sys
from pathlib import Path

RELEASE = re.compile(r"^##\s+\[?(?P<ver>[^\]\s]+)\]?\s*(?:-\s*(?P<date>\d{4}-\d{2}-\d{2}))?(?P<tail>.*)$")
INTERNAL = re.compile(r"\b(bump|upgrade[sd]?|dependenc\w+|deps?|refactor\w*|lint\w*|chore|typo|tests?|ci|rename[sd]?)\b", re.I)
JARGON = re.compile(r"\b(race condition|deadlock|mutex|queue|worker|thread|pool|cache|index|orm|migration script)\b", re.I)


def newest_release(lines):
    """Return (version, date, {group: [entries]}) for the first dated, non-yanked release."""
    release, group, found = None, None, []
    for line in lines:
        m = RELEASE.match(line)
        if m:
            release, group = m, None
            if m["date"] and "yanked" not in m["tail"].lower():
                found.append((m["ver"], m["date"], {}))
            continue
        if line.startswith("### "):
            group = line[4:].strip()
        elif re.match(r"^[-*]\s+", line) and release and found and release["date"] \
                and "yanked" not in release["tail"].lower() and group:
            found[-1][2].setdefault(group, []).append(re.sub(r"^[-*]\s+", "", line).strip())
    return found[0] if found else None


def triage(group, entry):
    if group == "Security":
        return "ASK", "a person decides if this goes on screen"
    if INTERNAL.search(entry):
        return "CUT", "reads as internal work"
    if len(entry.split()) < 4:
        return "REWRITE", "too vague to turn into a headline"
    if JARGON.search(entry):
        return "REWRITE", "names a component customers never see"
    if group in ("Deprecated", "Removed"):
        return "SCENE", "customers lose something, say it plainly"
    return "SCENE", ""


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("path")
    ap.add_argument("--title", type=int, default=3, help="title card seconds")
    ap.add_argument("--per", type=int, default=6, help="seconds per scene")
    ap.add_argument("--cap", type=int, default=40, help="runtime cap in seconds")
    ap.add_argument("--strict", action="store_true", help="exit 1 if ASK or REWRITE rows remain")
    args = ap.parse_args()

    rel = newest_release(Path(args.path).read_text().splitlines())
    if not rel:
        sys.exit("No dated, non-yanked release found.")
    ver, date, groups = rel

    print(f"Release {ver} ({date})\n")
    print("| Group | Entry | Verdict | Why |")
    print("|---|---|---|---|")
    scenes, open_rows = 0, 0
    for group, entries in groups.items():
        for e in entries:
            verdict, why = triage(group, e)
            scenes += verdict == "SCENE"
            open_rows += verdict in ("ASK", "REWRITE")
            print(f"| {group} | {e} | {verdict} | {why} |")

    runtime = args.title + scenes * args.per
    flag = "  <- over the cap" if runtime > args.cap else ""
    print(f"\n{scenes} scenes, about {runtime}s of {args.cap}s{flag}")
    if args.strict and open_rows:
        sys.exit(1)


if __name__ == "__main__":
    main()

The rules are deliberately dumb:

Skips what shouldn't be read. It ignores [Unreleased], because those lines haven't shipped. It also ignores any release marked [YANKED], because that release was pulled.
CUT. Words like bump, upgrade, refactor, lint and chore suggest internal work.
REWRITE. An entry under four words is too thin for a headline. An entry that names a queue, a worker or a deadlock describes something customers never see.
ASK. Anything under Security goes to a person, every time.
The runtime budget. A title card plus six seconds per scene, checked against a cap. This catches the "we have eight features and 40 seconds" problem before any scene exists.

A test run on an invented changelog

Here is the file I tested with. The app, Fieldnote, is made up so there is no real customer data in it.

## [Unreleased]

### Added
- Shared folders (behind a feature flag).

## [2.8.0] - 2026-10-14

### Added
- Offline mode for iOS.
- Tag filters in search.

### Changed
- Upgrade React to 19.1.
- Search results open faster on large libraries.

### Removed
- Dropped the legacy Markdown importer.

### Fixed
- Fix race condition in sync queue.
- Fix crash when opening notes over 10,000 characters.
- Misc fixes.

### Security
- Sanitize HTML in the note preview.

## [2.7.1] - 2026-09-30 [YANKED]

### Fixed
- Fix login redirect.

And what python changelog_triage.py CHANGELOG.md printed:

Group	Entry	Verdict	Why
Added	Offline mode for iOS.	SCENE
Added	Tag filters in search.	SCENE
Changed	Upgrade React to 19.1.	CUT	reads as internal work
Changed	Search results open faster on large libraries.	SCENE
Removed	Dropped the legacy Markdown importer.	SCENE	customers lose something, say it plainly
Fixed	Fix race condition in sync queue.	REWRITE	names a component customers never see
Fixed	Fix crash when opening notes over 10,000 characters.	SCENE
Fixed	Misc fixes.	REWRITE	too vague to turn into a headline
Security	Sanitize HTML in the note preview.	ASK	a person decides if this goes on screen

The footer reads 5 scenes, about 33s of 40s. The shared-folders flag and the yanked 2.7.1 never appear, which is the point.

Two rows deserve a second look. "Search results open faster on large libraries" got a SCENE verdict, and the script is right to let it through. But a speed claim invites a number, and the note doesn't contain one. If an agent writes "twice as fast" on that scene, it made the number up. I would catch that in the brief, not in the render.

The "Misc fixes" row is the other. No script can fix it. Someone who knows what shipped has to write the real line, and that is the whole argument for doing this triage before the agent runs.

Hand the table to Claude Code

Setup is the boring part and the docs cover it better than I would. In the CoAnimator app, Settings, General, Command line and agent skill has an install button for each, and the CLI docs cover the command. Claude Code comes from Anthropic's setup guide. If you want background on what the agent can do inside a project, this post covers it.

Then I would send the dated section, the table, and a brief like this:

Here is a triage table for Fieldnote 2.8.0 and the dated changelog section it came from. Treat the table as a proposal. For each row, confirm or overrule the verdict and give one sentence of reasoning. For REWRITE rows, propose a customer-facing line and quote the source words it came from. Do not state any number, speed or percentage that is not in the notes. Build nothing until I reply.

The last two instructions do most of the work. "Quote the source words" forces every headline to point at its entry, and "build nothing until I reply" turns the first answer into something you can correct for the price of one sentence. Each SCENE row also needs a screenshot or recording to attach, or the scene will be text on a background.

What I still check by hand

Once the build is approved, the render step is a single coa render <project>. For a quick look at the title card, --start 0 --end 6 renders only the first six seconds. The script can't check the rest, so I go through these:

Headline strength. "Large notes no longer crash the app" matches the crash entry. "Crashes are gone" doesn't.
Version and date against the tag. The card can say 2.8.0 while the repo's latest tag is v2.8.1 after a hotfix. git describe --tags --abbrev=0 prints the latest tag in one second.
Text outside the scenes. Closing cards and subtitles never passed through the table, and that is where stock claims like "faster than ever" show up.

Gate it in CI

--strict makes the script exit 1 while any ASK or REWRITE row is unresolved. I tested the exit code locally, and I haven't wired it into a release pipeline yet. The step itself is two lines:

- name: Changelog triage
  run: python changelog_triage.py CHANGELOG.md --strict

Any Security entry fails strict mode on purpose, so a person has to look at it. Once someone has, run that release without --strict.

The table prints to the job log, so whoever reviews the failed run sees exactly which rows need a person.

Where the heuristics break

It matches words, not meaning, and it will be wrong in both directions:

"Add CI status badge to dashboard" gets CUT because of "CI", though customers see that badge.
"Upgrade your plan from the app" gets CUT because of "upgrade".
"Add index of recent files" gets REWRITE because of "index".

That is why the script proposes and the agent and I decide. It also can't tell whether a change is visible to a customer, because it only sees the words.

One privacy point. The script runs locally, but whatever you paste into an agent can leave your machine for its provider. CoAnimator's quickstart says the same about files and frames sent to an AI provider. Delete embargoed rows from the table before pasting, and crop customer data out of screenshots.

FAQ

Does it work with changelogs that aren't in Keep a Changelog format?
It needs ## [version] - date headings and ### groups. GitHub's generated release notes have neither, so the parser would need a small change.

Does the script replace reading the notes?
No. It's a first draft of the cut list so the conversation with the agent starts from something concrete.

Do I need CoAnimator for this?
No. The table works with any agent or video workflow. I use CoAnimator for the render step.

Next step: let the PR decide

Regex is a fallback. The better signal is the person who wrote the change. A customer-facing label on the pull request, or a one-line release-note field in the PR template, would let the table come from labels and leave the regex to catch whatever nobody labeled. Then the triage happens at merge time, when the author still remembers why the change matters.

Try the script on your last release and see which rows you disagree with. Those are the decisions your changelog never recorded. If you want to turn the approved rows into a video, the CoAnimator desktop app is where I'd render them or you can use your existing video workflow.

I Built My Own MCP Client Instead of Using Claude Desktop

Sheen — Thu, 06 Aug 2026 11:53:30 +0000

Two hours. That's how long I stared at Connection refused before I gave up trying to debug Claude Desktop and just wrote my own client instead.

The server was running. I'd verified the config. I'd restarted everything twice. The problem was I had no idea where in the chain it was actually failing. Transport? Handshake? Session init? I was guessing. And I hate guessing.

Writing my own client didn't fix that specific incident (turned out to be a path issue in a JSON config file, obviously), but it meant I'd never be in that position again. Now when something breaks, I can read the stack trace instead of filing a mental bug report against a black box.

This is what I built, what I learned, and what the official docs don't tell you.

First: What a client actually is

I'll keep this short because most tutorials either skip it entirely or spend three paragraphs on it. MCP has three roles:

Host: your application. A pipeline, a script, a product.
Server: exposes tools, resources, and prompts to the model.
Client: opens exactly one connection to exactly one server, negotiates the protocol, and shuttles tool calls back and forth.

The one-to-one constraint is deliberate. A client doesn't fan out to multiple servers. It's scoped to one. If you want multiple servers, you run multiple clients (or use a gateway, more on that later). The reason this matters: it keeps connections sandboxed. A misbehaving server can't reach sideways into another server's session because there's no shared session to reach into.

The client itself has no capabilities to advertise. All it does is translate:

model output → tool call → server → result → back to model

The spec changed in July 2026 and most tutorials haven't caught up

This is the thing I wish I'd known before I started reading examples.

Tutorials from early 2026 and before show clients that open with an initialize handshake and then pass an Mcp-Session-Id header on every request after that. That session ID tied your client to one specific server instance. Fine for a single machine, painful for anything behind a load balancer.

The July 28, 2026 spec update dropped both. No initialize handshake. No session ID. Protocol version and capabilities now travel in _meta on every request, and remote server discovery moved to a new server/discover call.

For local stdio (which is the whole tutorial below), none of this changes your code right now. But if you copy an older tutorial and plan to extend it to Streamable HTTP later, you'll be starting from patterns that are already deprecated. Worth knowing before you build on top of them.

Why bother when Claude Desktop exists

Fair question. Claude Desktop works. Cursor works. For the use case they're designed for (a human, a chat window, some tools), they're fine.

I needed something different.

My specific problem was a data pipeline that runs on a schedule. There's no chat window. No human in the loop. The pipeline needs to call MCP tools, process the output, and move on. You can't shoehorn Claude Desktop into that. The MCP connection has to live inside the pipeline code itself.

Beyond my specific case, there are a few other situations where building your own client is the only real option:

When you need to intercept tool output before it hits the model. Prebuilt clients are pass-through by design. If a tool returns a payload with PII, internal metadata, or something oversized for your context budget, you have no way to filter it. A custom client gives you that interception point.

When you're embedding MCP into a product someone else will use. You can't ship a product that requires users to install and configure Claude Desktop. The client logic has to be inside your application.

When you need actual error messages. This was my original motivation. I wanted a stack trace, not a mystery.

What you need

The official MCP SDK covers Python, TypeScript, Java, Kotlin, C#, Ruby, and Rust. I'm going with Python. Lower friction for a tutorial, and the uv toolchain makes dependency management painless.

You'll need:

Python (latest stable) and uv installed
An Anthropic API key. Get one from console.anthropic.com
An MCP server to point it at. Your own works, Anthropic's weather quickstart server works, or browse mcp360.ai/mcps if you want a real production server to test against instead of a demo

Step 1: Set up the project

uv init mcp-client
cd mcp-client
uv venv
source .venv/bin/activate
uv add mcp anthropic python-dotenv
rm main.py
touch client.py

Before you write a single line of application code, deal with the API key:

echo "ANTHROPIC_API_KEY=your-key-here" > .env
echo ".env" >> .gitignore

I'm putting this first because a leaked key is the most common MCP security failure I've seen discussed in the community. Not clever protocol exploits. Just keys ending up in repos.

Step 2: The client class skeleton

import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()

class MCPClient:
    def __init__(self):
        self.session: Optional[ClientSession] = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()

The one thing here that every tutorial glosses over: AsyncExitStack.

It's not boilerplate. It's the thing that makes cleanup reliable when something goes wrong mid-connection. Without it, failed connections leave hung processes behind that you can't kill without hunting PIDs. I learned this the annoying way.

Step 3: Connecting to a server

async def connect_to_server(self, server_script_path: str):
    is_python = server_script_path.endswith('.py')
    is_js = server_script_path.endswith('.js')
    if not (is_python or is_js):
        raise ValueError("Server script must be a .py or .js file")

    command = "python" if is_python else "node"
    server_params = StdioServerParameters(
        command=command,
        args=[server_script_path],
        env=None
    )

    stdio_transport = await self.exit_stack.enter_async_context(
        stdio_client(server_params)
    )
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(
        ClientSession(self.stdio, self.write)
    )

    await self.session.initialize()

    response = await self.session.list_tools()
    tools = response.tools
    print("\nConnected. Available tools:", [tool.name for tool in tools])

This spins up the server as a subprocess and talks to it over stdio. That's the right call when client and server are on the same machine.

If your server is remote, the transport changes to Streamable HTTP, not SSE. I see a lot of tutorials still using SSE. The current spec supersedes it, so if you copy SSE-based transport code anywhere, flag it for replacement before you ship anything.

Step 4: The part that actually does things

async def process_query(self, query: str) -> str:
    messages = [{"role": "user", "content": query}]

    response = await self.session.list_tools()
    available_tools = [{
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    } for tool in response.tools]

    response = self.anthropic.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    final_text = []
    assistant_message_content = []

    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
            assistant_message_content.append(content)
        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input

            result = await self.session.call_tool(tool_name, tool_args)
            final_text.append(f"[{tool_name} called]")

            assistant_message_content.append(content)
            messages.append({"role": "assistant", "content": assistant_message_content})
            messages.append({
                "role": "user",
                "content": [{
                    "type": "tool_result",
                    "tool_use_id": content.id,
                    "content": result.content
                }]
            })

            response = self.anthropic.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1000,
                messages=messages,
                tools=available_tools
            )
            final_text.append(response.content[0].text)

    return "\n".join(final_text)

The thing to pay attention to in that loop: the client doesn't decide whether to call a tool. Claude does. All the client does is execute what Claude asked for, package the result as a tool_result message, and send everything back up for a final response.

If you find yourself writing client-side logic to override or second-guess Claude's tool choice, that's almost always a sign the tool descriptions are unclear, not that the client logic is wrong.

Step 5: Chat loop, cleanup, entry point

async def chat_loop(self):
    print("\nRunning. Type 'quit' to exit.")
    while True:
        try:
            query = input("\nQuery: ").strip()
            if query.lower() == 'quit':
                break
            response = await self.process_query(query)
            print("\n" + response)
        except Exception as e:
            print(f"\nError: {str(e)}")

async def cleanup(self):
    await self.exit_stack.aclose()

async def main():
    if len(sys.argv) < 2:
        print("Usage: python client.py <path_to_server_script>")
        sys.exit(1)

    client = MCPClient()
    try:
        await client.connect_to_server(sys.argv[1])
        await client.chat_loop()
    finally:
        await client.cleanup()

if __name__ == "__main__":
    import sys
    asyncio.run(main())

The try/except in the loop isn't optional. MCP tool calls fail for reasons the client has no control over: slow server responses, missing env vars on the server, malformed arguments. Without catching those, one bad query takes out the whole session. You want the session to survive a bad query, not restart from scratch.

Run it:

uv run client.py path/to/your/server.py

First response will take 20–30 seconds. The server subprocess is cold-starting, and Claude's first completion takes a moment. Subsequent queries are faster.

Errors I hit (and what they actually meant)

Error	What I thought	What it actually was
`FileNotFoundError`	Import problem	Wrong path to the server script
`Connection refused`	Port conflict	Server subprocess wasn't launching at all
`Tool execution failed`	Client bug	Server missing an env var
`Timeout`	Server crashed	Server was just slow; raising the timeout fixed it

The one that got me most: I was running the same server through Claude Desktop while testing my client. Claude Desktop has its own config file with its own paths. A stale path in one of them produces a FileNotFoundError that looks like it's coming from your code. It isn't.

If you're stuck on connection errors after double-checking paths, the problem is almost always server-side config, not the client code above. The MCP360 docs have a solid breakdown of the server-side setup issues that client-side debugging won't help you find.

The security stuff nobody puts in tutorials

An MCP client hands a language model the ability to trigger real actions on real systems. That's the whole point, and it's also the risk.

A threat-modeling paper from May 2026 found prompt injection attacks hiding inside tool descriptions across seven major clients. Not in tool output. In the description field itself. The attack tells the model to execute something it normally wouldn't, and it works because most clients pass tool metadata straight to the model without any inspection. Across 13,875 servers analyzed, that's a real problem.

What I actually do:

Read tool descriptions before connecting. A tool called get_weather that describes write access to the filesystem doesn't make sense. That's a red flag.
Minimum-permission credentials. Don't hand a server an API key that can do more than that server needs.
Human confirmation before write/delete/send. I add one input("Confirm? y/n: ") before any tool call that's irreversible. One line. Worth it.
.env in .gitignore before first commit. Not after.

What breaks next and how to fix it

The client above handles one server. The moment you need two, you're copy-pasting the connection block. Three servers, you're doing it again. At some point that becomes its own maintenance problem.

The pattern most people land on is a gateway: one connection point that sits in front of multiple servers, handles auth centrally, and exposes everything through a single endpoint. Your client code above doesn't change at all. You just point it at the gateway URL instead of individual server scripts. MCP360 is built around that model if you want something you can set up quickly rather than build from scratch.

The other thing that breaks: config file sprawl. Claude Desktop, Cursor, and Windsurf all store MCP server configs in different paths. If you're running servers across more than one of those clients, keeping configs in sync gets tedious. mTarsier is an open-source desktop tool that reads all of them from one place. It's from the MCP360 team and it's free.

For transport, the next step after stdio is Streamable HTTP. When you make that move, strip out any session ID assumptions from your connection logic. The July 2026 spec removed session pinning entirely, so anything that depends on Mcp-Session-Id will fail against a compliant server.

That's the full build. The code above is about 80 lines total and handles the complete client lifecycle. From here the interesting problems aren't in the client. They're in what you connect it to and what you do with the results.

What are you building this for? Curious what use cases people are actually running MCP against.

The biggest thing I got wrong about MCP? Thinking it was trying to replace REST APIs. After building with both, I realized it's a new layer for AI, not a replacement for existing APIs.

Sheen — Wed, 22 Jul 2026 12:01:21 +0000

Sheen

Jul 22

Stop Comparing MCP to REST APIs! They're Not Competing.

#mcp #api #ai #webdev

5 min read

Stop Comparing MCP to REST APIs! They're Not Competing.

Sheen — Wed, 22 Jul 2026 11:53:20 +0000

MCP keeps coming up in every AI dev conversation right now. And almost every time, someone asks: "So does this replace REST APIs?"

No. And the comparison itself reveals a misunderstanding worth clearing up - one I ran into myself when I first started building with MCP.

TL;DR: REST APIs are for developer-to-system calls. MCP is for model-to-system calls. They're not competing - in most setups, MCP wraps your existing REST APIs. The math shifts from N×M integrations to N+M. That's the whole game.

The Problem I Kept Running Into

When I first tried giving an LLM a raw REST API to work with, it kept hallucinating parameter names, calling the wrong endpoints, and mangling request bodies - not because the model was broken, but because raw HTTP endpoints carry zero semantic context.

I read POST /tickets and checked the docs. The model couldn't do that reliably at runtime. There's nothing in the endpoint that tells the model what priority means, which values are valid, or when to use this endpoint versus POST /issues.

MCP fixes this by replacing endpoints with named tools. Instead of POST /tickets, the model calls create_support_ticket with typed, described inputs: title, priority (one of: low, medium, high, critical), description. Every parameter has a description written for the model, not a human developer.

The model now knows what the tool does, what it expects, and when to use it. That context is what made the difference between reliable tool use and constant hallucination in my own builds.

What They Each Actually Do

	REST / GraphQL / gRPC	MCP
Designed for	Developer-to-system communication	Model-to-system communication
Caller	Code you wrote	An AI agent at runtime
Discovery	You read the docs	Model discovers tools dynamically
Context	None - caller already knows the schema	Rich - names, descriptions, types per parameter
Best for	Stable, performance-critical integrations	Agentic workflows, multi-tool orchestration
Auth model	OAuth, API keys, RBAC (mature)	Still maturing - prompt injection is a real risk
Debugging	Standard HTTP tooling	Depends on the client implementation
Replaces the other?	No	No

The right framing isn't "which one" but "which layer." Most production setups I've seen (and built) that use MCP still have REST APIs running underneath - the MCP server is a translation layer that exposes those APIs to models in a format they can actually use reliably.

A Quick Code Comparison

Here's what the difference looks like in practice. Same action - creating a support ticket - handled two ways.

Raw REST call from your agent code:

// Agent has to know the endpoint, headers, body shape, and error handling
const res = await fetch("https://api.example.com/tickets", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title: "Login broken",
    priority: 2,        // what does 2 mean? the model doesn't know
    type: "support"     // is this required? the model isn't sure
  })
});

MCP tool definition:

{
  "name": "create_support_ticket",
  "description": "Creates a new support ticket. Use when a customer reports a bug or needs help.",
  "inputSchema": {
    "title": { "type": "string", "description": "Short summary of the issue" },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"],
      "description": "How urgently this needs attention"
    }
  }
}

The model calling the MCP tool knows exactly what to pass and why. The model hitting the raw REST endpoint is guessing.

The N×M Problem (This Is the Real Insight)

Before I understood MCP properly, I kept rebuilding the same integrations.

If you have N models and M tools, the traditional approach needs N×M integrations. Each model needs its own connection to each tool: its own auth logic, its own schema handling, its own error handling. Every new tool means N new integrations. Every new model means M new integrations.

MCP changes the math. Each model implements an MCP client once. Each tool implements an MCP server once. Any client can talk to any server because they share the same protocol.

N×M becomes N+M.

This is the actual value proposition - not "MCP vs REST" but "a shared protocol that stops you from rebuilding the same integrations over and over."

The Part Most Articles Skip: Dynamic Discovery

REST APIs are static contracts. You define endpoints, the client knows them, done.

MCP supports runtime discovery. When my agent connects to an MCP server, the server advertises its available tools, their input schemas, and what they return. The agent learns what capabilities exist without prior configuration.

This matters for agentic workflows where the set of available tools changes. I can spin up a new MCP server, connect it to the gateway, and the model discovers it automatically. No code changes on the client side.

This is borrowed from the Language Server Protocol (LSP) - the same mechanism that lets your editor support a new programming language without being rewritten. Once I made that connection, MCP clicked for me immediately.

A Concrete Example From Something I Built

I worked on a support automation agent that needed to:

Look up a customer record
Check their open tickets
Create a new ticket if none exists
Notify the customer by email

With raw REST: My agent code needed to know four endpoints, handle four different auth schemes, parse four response formats, and implement retry logic for each. Every time one of those APIs changed, I updated integration code.

With MCP: I exposed four tools - get_customer, list_tickets, create_ticket, send_notification - each with clear descriptions and typed parameters. The agent calls them by name. The MCP server handles the actual HTTP calls. When the underlying API changed, I updated the MCP server, not the agent.

The agent stayed clean. The tools stayed focused. The model could actually use them reliably.

What I Use When

Traditional APIs:

Connecting two services in code I control
Performance and latency are the primary constraint
I need ACID transactions (SOAP/gRPC territory)
The caller always knows exactly which endpoint to call

MCP:

An AI agent is the caller
The set of tools changes or grows over time
I'm building multi-step agentic workflows
I want one integration point for multiple AI clients (Claude Desktop, Cursor, custom agents)

Both together (most common in my work):

My MCP server wraps existing REST APIs - this is almost always the pattern
REST handles structured service-to-service calls, MCP handles agent-to-tool calls
I want AI capabilities without rearchitecting my backend

Where I Think This Is Going

REST isn't going anywhere. It handles core business logic where consistency matters. MCP adds a layer on top - one that makes AI agents first-class consumers of existing infrastructure without requiring them to understand API schemas at runtime.

If you're already running REST APIs internally, converting them to MCP tools is mostly editorial work: decide which operations to expose, write tool names and parameter descriptions that a model can interpret, and test how the model actually calls them before shipping. The backend doesn't change.

The interesting design question I keep running into isn't whether to use MCP or APIs - it's which operations deserve to be MCP tools, how precisely to describe their parameters, and how to scope what the agent can and cannot do.

If you want to go deeper on MCP - tool design patterns, server architecture, real integration examples - I've been writing about all of it over at MCP360.

💬 Have you built an MCP server on top of existing REST APIs? What broke first - the tool descriptions, the auth, or something else entirely? Drop it in the comments, I'm genuinely curious what failure modes look like across different stacks.

How to Add an AI Chatbot to Shopify: Complete Setup Guide for 2026

Sheen — Tue, 16 Jun 2026 06:31:20 +0000

A Shopify AI chatbot is a conversational assistant that has a direct connection to your store’s products, policies, and customer data. AI chatbots can understand customer questions in natural language and respond to them with the information that is available in your Shopify store, unlike traditional chat widgets that rely on pre-written scripts.

Most Shopify AI chatbots work by combining three sources of information: your product catalog, your support content, and live store data. After connecting to Shopify, the chatbot can access product details, inventory status, shipping policies, FAQs, and order information. When a customer asks a question, the chatbot retrieves the relevant information and generates a response in real time. More sophisticated setups can also trigger actions such as checking an order status, recommending products or handing the conversation over to a support agent.

For Shopify merchants, the value is practical, not theoretical. Customers can find answers without leaving the product page, track orders without submitting a support ticket, and find the right products faster. Support teams spend less time answering repetitive questions and more time dealing with exceptions needing human judgment. This means a quicker buying experience for customers and less manual work for your team.

In this guide, you'll learn how to connect YourGPT to Shopify, train it on your store content, setup automated workflow and launch an AI chatbot capable of assisting customers across your storefront and other channels like whatsapp, instagram, etc.

What You'll Need Before You Start

Before setting up your Shopify AI chatbot, make sure you have the following:

A Shopify store with admin access so you can edit your theme files and publish changes.
A YourGPT account to create, train, and manage your chatbot.
Help center content or FAQs that answer common customer questions.
Store policies, including shipping, returns, refunds, and contact information.
Product information, such as descriptions, collections, and sizing details, if you want the chatbot to answer product-specific questions.

If your support content is incomplete or outdated, update it before training the chatbot. The quality of your chatbot's responses depends on the information you provide.

How to Set Up an AI Chatbot for Shopify

Following are the steps to add an AI Chatbot to your Shopify store using YourGPT:

Step 1: Create Your YourGPT Workspace

Go to YourGPT and create an account. Once you're signed in, you'll have access to the chatbot builder, training tools, and integrations dashboard.

Step 2: Train Your Chatbot with Store Content

Add the information your chatbot will use to answer customer questions.
Import your help center articles, FAQs, product descriptions, shipping details, return policies, and other customer-facing content. You can upload documents, add website links, or connect your sitemap.
The chatbot uses this content to generate responses, so review your information before importing it.

Step 3: Customize the Chatbot

Adjust the chatbot to match your store.
You can update the chatbot name, welcome message, and brand colors. If needed, add quick replies or lead capture fields through the visual editor.

Step 4: Generate and Copy the Chatbot Script

Open the Integrations section in your YourGPT dashboard and copy the widget script for your chatbot.
You'll add this code to your Shopify theme in the next steps.

Step 5: Access Your Shopify Theme Code

In your Shopify admin panel:

Go to Online Store → Themes.
Find your active theme.
Open the options menu next to the theme.
Select Edit code.

Step 6: Locate the theme.liquid File

In the code editor:

Open the Layout folder.
Select theme.liquid.
Scroll to the bottom of the file.

Step 7: Paste the Chatbot Script

Paste the YourGPT widget script directly above the closing </body> tag.
Double-check that the entire script has been added without changing any existing code.

Step 8: Save Changes and Test Your Chatbot

Click Save in the top-right corner of the editor.
Return to your storefront and refresh the page. Your chatbot should now appear and be ready to answer customer questions.

Real Use Cases: What Your Shopify AI Chatbot Can Handle

Following are the real use cases your shopify AI chatbot can handle:

Product Recommendations
Customers often have trouble deciding between similar products, or figuring out the right size or comparing features. Your chatbot can answer questions about your product and recommend suitable products based on your customer’s needs, budget or preferences.

Order Tracking and Shipping Updates
Customers shouldn't have to contact support to check an order status. When combined with information from your store, your bot can provide shipping info, estimated delivery dates, and links to tracking pages.

Returns and Refund Requests
It’s normal to have questions about returns, especially once you’ve bought something. Your chatbot can explain your return policy, guide you through the process for refunds, and direct customers to the right support channel when an issue requires manual review.

Cart Recovery
Some shoppers leave because they can’t find the information they want. Your chatbot is able to answer last-minute questions about pricing, shipping costs, delivery times or product details that could otherwise prevent a purchase.

Common Customer Support Questions
Your chatbot will be able to answer frequently asked questions about store policies, payment methods, dimensions, contact details, business hours and account management. If a request requires human assistance, the chatbot can gather key information and pass the conversation to your team.

Conclusion

Adding an AI chatbot to your Shopify store does not require custom development or a complex setup process. With YourGPT, you can train a chatbot on your existing content, add it to your Shopify theme, and start assisting customers directly on your storefront.

The quality of your chatbot depends on the information you feed. Keep your FAQs, product details, and store policies up to date, and review customer conversations regularly to identify gaps or outdated responses.

Once your chatbot is live, start with the questions your support team answers most often. This helps you improve response quality over time and gives customers faster access to the information they need.

FAQ's

Do I need coding skills to add an AI chatbot to Shopify?
No. You only need to copy the chatbot script from YourGPT and paste it into your Shopify theme file. No custom development or app installation is required.

How do I train a Shopify AI chatbot?
Train your chatbot using the content your customers already rely on, including FAQs, help center articles, product descriptions, shipping information, and return policies.

Can I use my existing FAQs and help center content?
Yes. YourGPT can use your existing support content, so you do not need to create a separate knowledge base from scratch.

What content sources and file formats does YourGPT support?
You can train YourGPT using website URLs, sitemaps, PDFs, documents, and direct text input. This makes it easy to import content from your help center, product pages, and policy documents.

Can a Shopify AI chatbot track orders?
Yes. YourGPT can access Shopify order data to help customers check order status, delivery updates, and tracking information without contacting your support team.

Can the chatbot answer product questions?
Yes. After training, the chatbot can answer questions about product features, sizing, pricing, availability, and store policies based on the content you provide.

Where do I add the chatbot script in Shopify?
Paste the widget script in the theme.liquid file, directly above the closing tag.

How to Convert Any REST API into a MCP Server

Sheen — Wed, 03 Jun 2026 13:25:25 +0000

APIs were built for developers, not AI agents. A developer reads the docs, figures out which endpoint to call, and knows what to put in the request body. An LLM does not have that luxury. Give it a raw REST API and it will hallucinate parameter names, call the wrong endpoint, or format the request body incorrectly, not because the model is bad, but because raw HTTP endpoints carry zero semantic context.

This is the problem MCP solves. Instead of pointing an AI client at endpoints, you expose named tools with explicit input definitions. The model knows what each tool does, what it expects, and what it returns. No guessing.

This guide walks through converting an existing REST API into an MCP server using MCP360, without touching the backend.

What MCP Actually Changes

The API itself does not change. The backend stays exactly as it is.
What MCP adds is a translation layer. Instead of POST /tickets, the AI client calls a tool named create_support_ticket with typed inputs: title, priority, and description. The tool definition tells the model what each field means, what is required, and what format they expect.
That context is what makes the difference. Without it, the model is guessing. With it, the model can reliably select the right tool and populate it correctly.
The work of converting a REST API to MCP is mostly editorial: decide which operations to expose, write clear tool names and descriptions, and define inputs tightly enough that there is no ambiguity.

Step 1: Create a New MCP Server in MCP360

Log in to MCP360, open the MCP Servers section, and click Create New Server.
Select Custom MCP Server, fill in the name and description, and click Create MCP.
MCP360 generates your MCP endpoint and opens the configuration screen.

Step 2: Go to the Tools Section

Inside the MCP configuration page, navigate to Tools and click Import Tools.
This is where REST endpoints get mapped to MCP tools.

Step 3: Select Custom API Tool

In the Import Tools window, choose Custom API Tool.
This lets you point MCP360 at any REST endpoint and define how it should be exposed as a tool.

Step 4: Configure the Tool

Fill in:

Tool name : use something descriptive, like get_customer_orders not get_data
Tool description : Write this for the model, not for a human developer. Be explicit about what the tool does and when to use it
Request method : GET, POST, etc.
Endpoint URL : the full API endpoint
If the API needs authentication, add the required headers here.
Then configure AI parameters. These are the input fields the model will populate when it calls the tool. For each parameter, set a clear name and description. This is the part most people rush through and then wonder why the model keeps sending wrong values.
A parameter named id with no description is useless to a model. A parameter named customer_id described as "the unique identifier for the customer, found in the user profile response," is not.

Step 5: Import the Tool

Review everything, then click Import Tool.
MCP360 creates the tool from your configuration. It will show up in the Tools section once imported.

Step 6: Test Before You Connect Anything

Do not connect an AI client until you have tested the tool manually.
Open the Tools section, find your tool, and click Test API.
This fires the actual HTTP request and shows you exactly what comes back. It is much faster to debug a bad header or wrong parameter here than after hooking it up to a model.

Step 7: Check the Test Response

Request status: 200 OK
Response data returned in the panel
Valid JSON output
If all three check out, the MCP tool is communicating with the API correctly and is ready to use.

Common Errors and how to fix them

Auth failures:
Check the API key, the Authorization header format, and whether the API allows requests from external sources. Most auth issues come down to a missing Bearer prefix or a header key typed incorrectly.
Wrong endpoint config:
Confirm the URL, verify the HTTP method matches what the API actually expects, and make sure the API returns JSON. A GET configured as POST will fail silently in some cases, which makes it harder to diagnose.
Parameter mismatches:
If the tool runs but returns garbage, the AI parameters are probably mapped to the wrong fields. Walk through each one and confirm it points to the right key in the request body or query string. Also check whether any parameters are hardcoded that should be dynamic; if the model is expected to supply a value, it cannot be fixed in the config.

Conclusion

The actual conversion work here is not technical. The backend does not change. What takes judgment is deciding which endpoints to expose, how to name and describe tools clearly, and how to define parameters in a way the model can use without ambiguity.
Start with two or three high-value operations. Test them properly. See how the model actually calls them before adding more. A small set of well-defined tools is significantly more reliable than a large set of poorly defined ones.
MCP360 handles the infrastructure so you are not writing server code from scratch, but the quality of the tools you get out depends entirely on how precisely you define them going in.