DEV Community: Omer Faruk Kolip

I built an MCP server for Instagram — 16 tools, and everything the MCP publishing pipeline has quietly changed since my last one

Omer Faruk Kolip — Wed, 22 Jul 2026 12:50:18 +0000

A couple of months ago I wrote about shipping xtapdown-mcp — 14 X/Twitter tools as an MCP server. Since then I built the Instagram sibling — instapdown-mcp — 16 tools wrapping instapdown.com's public surface (Reels/Story/carousel downloaders, engagement audit, live hashtag search, Reels hook library, best-time-to-post for 17 markets, 750-date 2026 content calendar).

I thought I was just going to run the same playbook again. I wasn't. Between the two shipments, the MCP publishing pipeline changed in half a dozen small-but-annoying ways that would have burned an entire afternoon if I hadn't just seen them fresh. This post is that unlock — everything I'd do differently on shipment #2, and every schema/registry/scorer edge case that's landed since the first one.

If you're publishing your first MCP server: read the XTapDown post first, then this one. If you're publishing your second, this is the one to skim.

The setup — same shape as before

Same stack as xtapdown-mcp:

TypeScript + @modelcontextprotocol/sdk
stdio transport for local MCP clients
npm for install (npx -y instapdown-mcp)
zod schemas that double as the tool's input contract

The tool handlers are pure functions calling instapdown.com/api/*. No auth, no per-user state — everything the MCP surfaces is public data that the web tools already return.

16 tools, roughly a page of code each. The whole server, including the embedded static datasets (Buffer 2026 best-time data for 17 markets, 25 curated hashtag seed niches, the 2026 content calendar with per-market playbooks) is ~900 lines of TypeScript.

The Instagram-specific choice worth calling out: the downloader tools don't scrape. They call instapdown.com/api/download, which fronts a 4-layer extractor fallback chain (Meta CDN direct → RapidAPI social-scraper → Apify actor → community btch-downloader). When Meta rotates a GraphQL doc_id and the primary extractor fails, the same call transparently falls through to the next layer. From the MCP client's perspective it just… works. From my perspective it means one broken extractor doesn't turn into a broken Claude Desktop experience overnight.

Same syndication-endpoint spirit as X, different plumbing: put a real fallback chain on the server side, keep the MCP layer thin.

What actually changed since XTapDown

This is the "shipment #2 delta" — the parts that would have blindsided me if I'd shipped this straight off the old playbook.

1. `server.json` grew a `transport` field

Old shape from a few months ago:

{
  "name": "io.github.farukkolip/xtapdown-mcp",
  "description": "...",
  "packages": [
    { "registryName": "npm", "name": "xtapdown-mcp", "version": "..." }
  ]
}

Current shape (schema 2025-12-11):

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.farukkolip/instapdown-mcp",
  "description": "...",
  "version": "0.1.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "instapdown-mcp",
      "version": "0.1.1",
      "transport": { "type": "stdio" }
    }
  ]
}

Four renames + one required field, all now enforced at registry-submission time:

packages[0].registryName → registryType
packages[0].name → identifier
top-level version — now required (previously implicit from packages)
packages[0].transport — new required object, one of {stdio, streamable-http, sse}, stdio has no url, the other two do
description — hard cap at 100 chars, silently truncated for me last time, hard-rejected now

If any of these are wrong, mcp-publisher publish returns a 422 with a JSON blob listing all offenders at once. Fix them in one go rather than round-tripping.

2. `mcp-publisher` device tokens are short-lived

mcp-publisher login github gives you a device code that expires in ~30 seconds if you don't paste it into the GitHub /login/device page fast enough. The retry path is confusing — if you re-run login, you get a new code, but the token from a successful login lives ~10 minutes.

If your publish step takes longer than that (e.g. because you got a validation error and spent a minute fixing it), you'll hit 401 Invalid or expired Registry JWT token and have to login github again. Fine once you know it — burned me twice before I recognised the pattern.

3. Glama's scoring is layered now, not just "gated by a Dockerfile"

Old model: Glama built your Docker image, ran a couple of checks, gave you an A/B/C score.

New model: 10-item Server Quality Checklist. Every red X locks the score at whatever it currently is. The full list, from what I hit on instapdown-mcp:

Has a Glama release
Server Coherence (tool descriptions consistent with the server description)
Tool Definition Quality (zod → JSON schema round-trip is clean)
Maintenance (weighted signal — commits + releases + issue triage history + CI + vuln alerts)
Has a permissive license
Has README
Active usage (someone has actually called a tool via Glama's sandboxed MCP Inspector)
Has valid glama.json (see below)
Author verified
Has related servers (user-linked, not the auto-suggested "related" grid)

The two that quietly bit me:

glama.json schema evolved. The old shape ({"build": {"commands": [...]}}) still works for the Dockerfile builder but doesn't validate against the current $schema, so the checklist marks you red on "Has valid glama.json" even while the build passes. Current shape:

{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": ["your-github-handle"],
  "build": {
    "nodeVersion": "20",
    "buildSteps": ["npm ci", "npm run build"],
    "cmdArguments": ["mcp-proxy", "--", "node", "dist/index.js"]
  }
}

The maintainers array is what lights up the "Maintainer" cell on the Maintenance score card. Without it, that cell shows a dash even after you claim ownership via GitHub OAuth.

"Has related servers" needs a user-submitted related server. Glama's auto-populated "Related" grid (based on tag / category similarity) does not count. You have to open the Related Servers tab → Suggest Server → link to something you know is genuinely related. In my case: xtapdown-mcp as the TapDown sibling. That flipped the last red X to green.

4. Maintenance score has a floor for new repos — even with everything green

Even with all 10 checklist items green, a 1-day-old server tops out at Maintenance = B. Glama's weighted signal factors in:

Number of stable releases in 12mo (I had 1)
Issue triage history (I had 0 issues)
Response time SLA verified against real interactions (nothing to verify yet)
Contributor count / commit cadence over time

None of these can be forced. They fill in over weeks. xtapdown-mcp is A/A/A now, but that took months of activity — not something I did on shipment day.

Practical takeaway: don't wait for Maintenance A before opening your awesome-mcp-servers PR. Ship at A/A/B, note in the PR comment that the maintenance signal is time-based, and let the maintainer merge on the strength of the other nine green checks.

5. PulseMCP no longer has a submission form

The old pulsemcp.com/submit was a real form. Today it's a static page that says:

We ingest entries from the Official MCP Registry daily and process them weekly. If it has been a week since you published there, or want to make other adjustments to your listing, please email us.

So it's now genuinely just "publish to the Anthropic Registry and wait." Same for mcp.so, cursor.directory/mcp, and a couple of the smaller directories — Anthropic Registry has become the source of truth that everything else syncs from.

Net effect: the article's original "5 channels" list collapses to 3 things you actually do manually: npm publish, Anthropic Registry publish, awesome-mcp-servers PR. Everything else auto-syncs.

The publishing sequence I'd run today, if I were shipping shipment #3

Write the server. Add node:test structured tests — the checklist under Tool Definition Quality now looks for structured test files, not just an ambient test script.
Add a real Dockerfile and glama.json with the current schema and maintainers set. Don't wait until later.
npm publish --access public first — that establishes the identifier before anything else references it.
mcp-publisher login github and publish in quick succession, one session, before the JWT expires. If validation fails, fix and re-run login, don't try to bluff the same token through.
Fork awesome-mcp-servers, sync the fork if it's stale (mine was 719 commits behind), edit the README on the web, open the PR. Include the Glama score card badge markup so the maintainer's bot doesn't flag "missing badge" even if the score is stubbing to A/A/C for the first few hours.
Submit to Glama once. Then wait. Then click Sync Server on the Repository tab once the daily crawl misses your latest push (it will — Glama's daily sync is calendar-day, not push-triggered).
Fill the last-mile checklist items — Categories on the Profile tab, xtapdown-mcp-equivalent Related Server, one tool call via the MCP Inspector's Try in Browser (that's what registers "Active usage").
Comment on the awesome-mcp-servers PR with the final score screenshot and the maintenance-B caveat. Sit back.

Everything else — PulseMCP, mcp.so, cursor.directory — happens without you.

The bit that didn't need re-learning

The MCP SDK itself. @modelcontextprotocol/sdk is stable, InMemoryTransport still makes CI tests trivial, server.tool(name, description, zodShape, handler) still reads exactly like the docs say. If anything, the ergonomics improved — the SDK's callTool result now types cleanly through unknown without needing the manual cast I used the first time.

The publish process for shipment #2 took about 90 minutes of my time end-to-end, most of which was learning the deltas above. The code itself — 16 tools wrapping a REST API I already had — took closer to 3 hours. If you have a REST API and an audience of AI-assistant users, that ratio (3:1 for code:publishing) is probably the least misleading estimate I've seen for this kind of project.

What's next

YouTube next. tiktapdown-mcp is already live — same publishing pipeline as this one, I just never wrote it up separately because nothing new about the process had surfaced by that point. That's part of why this post covers the deltas from xtapdown-mcp directly.

The TapDown-family plan is a five-site set (TikTok, X, Instagram, YouTube, Pinterest) with a shared publishing pipeline and a matching MCP Registry naming scheme (io.github.farukkolip/<site>-mcp). Three of five are live; YouTapDown and PinTapdown are queued. Once all five are up, I'll consolidate them into a single Product Hunt launch as "MCP standard for creator toolkits" rather than pinging PH five times.

Try instapdown-mcp

Install: npx -y instapdown-mcp
Claude Desktop config: full instructions
Source: github.com/farukkolip/instapdown-mcp
npm: instapdown-mcp
Glama: glama.ai/mcp/servers/farukkolip/instapdown-mcp
The web tools it wraps: instapdown.com — free, no signup

If you ran into any of the schema/scoring changes above shipping your own MCP server this month, drop a comment — I want to know what other quiet migrations are out there so shipment #3 goes cleaner.

I built an MCP server for X (Twitter) — 14 tools in ~600 lines, here's what I learned

Omer Faruk Kolip — Tue, 14 Jul 2026 12:54:28 +0000

I ship a free X (Twitter) creator toolkit at xtapdown.com — 17 web tools for downloading tweets, generating hashtags, calculating engagement, splitting threads, that sort of thing. A few weeks ago I wrapped 14 of them as an MCP server and published it on npm, the Anthropic MCP Registry, Glama, and got it merged into awesome-mcp-servers.

The whole thing is ~600 lines of TypeScript. Here's what I learned along the way, and everything that actually mattered vs. the stuff I over-thought.

Why MCP over just having a REST API

I already had a REST API powering the web tools. I could have documented it and said "call these endpoints." Nobody would have.

The problem with a REST API for AI use cases: the LLM has to know your API exists. If nobody adds xtapdown.com to their system prompt or context, it might as well not exist. MCP inverts that — the client discovers your tools once, and from then on, whenever the LLM decides "I need to download a tweet," your tool is right there in its tool list.

I built the web tools first, spent months writing content around them, and got approximately zero traffic from AI assistants. Two weeks after publishing the MCP server, it had 500+ npm downloads. Different distribution channel, different mechanics.

TL;DR: MCP is a distribution primitive for tools that AI assistants should call directly. If your product's core use case fits into a single LLM turn ("download this tweet", "give me hashtags for AI"), MCP is a much better fit than a REST API you have to onboard people onto.

The stack

Nothing exotic:

TypeScript + @modelcontextprotocol/sdk
stdio transport for local Claude Desktop / Cursor / Cline use
Streamable HTTP transport for remote clients
npm as the primary distribution channel (npx -y xtapdown-mcp runs it with zero setup)

The tool handlers are pure functions. No database, no session state, no auth (the underlying data endpoints are public). This keeps the whole thing small enough that anyone can read the source and audit it before running it.

// One tool handler, roughly:
server.tool(
  'download_tweet',
  {
    url: z.string().url().describe('X/Twitter post URL'),
    include_media: z.boolean().optional(),
  },
  async ({ url, include_media }) => {
    const tweet = await fetchTweet(url);
    return {
      content: [{ type: 'text', text: formatTweet(tweet, include_media) }],
    };
  },
);

Fourteen of these, each 20-40 lines. That's the whole MCP surface area.

The syndication endpoint trick

The single most useful thing I want to share, because it took me a day of digging to find:

X has a public JSON endpoint that returns full tweet data, no auth, no rate limits I've hit. It's the endpoint the embed widget uses. It's been stable for years. You get:

Full text with entities
All attached media (video with variant URLs, images with source resolutions, GIFs as MP4)
Author info
Engagement stats (likes, retweets, replies, bookmarks, quotes)
Reply-to metadata for thread walking

I use it for download_tweet, get_tweet_screenshot_url, and thread reconstruction. In three months of production use across two sites, I've seen exactly one rate limit — during a viral link storm from a big Reddit thread.

Search for cdn.syndication.twimg.com/tweet-result. That's your endpoint. Handle the CORS on your own server, cache the response, done.

Caveat: this is a public endpoint but it's not a documented API. It could change. Have a fallback plan (or at least monitoring) if you build something serious on top of it.

Publishing — this is where MCP gets weird

Building the server is 10% of the effort. Getting it discoverable is 90%. There are five separate channels and each has its own quirks:

1. npm

Straightforward. Publish with npm publish --access public. The package name matters — mine is xtapdown-mcp which matches the site (xtapdown.com). Symmetry helps discoverability.

Add to package.json:

{
  "mcpName": "io.github.farukkolip/xtapdown-mcp"
}

This is the canonical ID the Anthropic MCP Registry uses. Reverse-DNS style, tied to your GitHub org/user. Get this right on first publish because it's a pain to change.

2. Anthropic MCP Registry

Official registry from Anthropic. Uses a Go CLI called mcp-publisher (get it from the modelcontextprotocol/registry releases, not npm — I lost 20 minutes to that).

You need a server.json in your repo:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.farukkolip/xtapdown-mcp",
  "description": "14 X (Twitter) creator tools as an MCP server",
  "repository": {
    "url": "https://github.com/farukkolip/xtapdown-mcp",
    "source": "github"
  },
  "packages": [
    {
      "registryName": "npm",
      "name": "xtapdown-mcp",
      "version": "..."
    }
  ]
}

Then:

mcp-publisher login github
mcp-publisher publish

Validation is strict. Description over 100 chars → rejected. Schema URL wrong → rejected. Repository URL missing .source → rejected. Get all three right the first time.

3. Glama

Glama auto-discovers MCP servers from GitHub and builds a Docker image to test them. If the build fails, they mark the badge red and the score is null.

Two gotchas:

They auto-detect pnpm if pnpm-lock.yaml exists even if your project uses npm. Add a glama.json at repo root overriding the build:

  {
    "build": {
      "commands": ["npm ci", "npm run build"]
    }
  }

The badge requires a LICENSE file. Not just "license": "MIT" in package.json — the actual LICENSE file at repo root. Add one and their scanner picks it up on the next refresh.

Got both right → A/A/A score, verified badge.

4. awesome-mcp-servers

The punkpeye/awesome-mcp-servers repo. One-line PR adding your server in the alphabetically correct spot in the right section. Include the Glama badge (they require it now via a GitHub Actions bot).

My PR got merged in a couple of days. Merge rate for real projects with good descriptions is high — the maintainer is friendly.

5. PulseMCP + mcp.so + others

These are third-party directories. Most of them auto-sync from the Anthropic Registry, so publishing there automatically populates the rest. Only PulseMCP needed a manual form for me.

Skip Smithery. I know it's on every "how to publish MCP" guide, but the current publishing flow is awkward and the audience-per-effort ratio is bad compared to the other five channels.

Testing this thing

For local dev, add to claude_desktop_config.json:

{
  "mcpServers": {
    "xtapdown": {
      "command": "npx",
      "args": ["-y", "xtapdown-mcp"]
    }
  }
}

Restart Claude Desktop. In a new chat, ask:

"Download this tweet for me: https://x.com/AnthropicAI/status/..."

If everything works, Claude will call download_tweet and hand you back the media URLs and the tweet text.

For CI, the MCP SDK ships a runInMemory test harness. Roughly:

import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
const client = new Client({ name: 'test', version: '0.0.1' }, { capabilities: {} });
await client.connect(clientTransport);

const result = await client.callTool({
  name: 'download_tweet',
  arguments: { url: 'https://x.com/AnthropicAI/status/1234...' },
});

Faster than spinning up a real client, catches most breakage.

What I'd do differently

Do this first, not last: decide your mcpName (the reverse-DNS ID) before you publish anywhere. It has to match across npm, Anthropic Registry, and Glama. Changing it later means republishing under a new identifier and losing whatever discoverability the old one built.

Don't overthink tool naming. I spent hours agonizing over download_tweet vs get_tweet vs fetch_tweet_media. In practice the LLM picks the right tool from the description regardless of the name, as long as the name isn't actively misleading.

Ship the CI test harness on day one. I skipped it initially, then had to add it after a silent regression broke get_x_trends for a week. Nobody complained because nobody was watching, but I noticed a drop in npm downloads and traced it back.

Distribution beats tool count. I have 14 tools. Half of them are probably never called. But 14 sounds better in the readme than 6, and once someone's installed the server, adding a rarely-used tool costs nothing.

What's next

I'm building the same pattern for TikTok (tiktapdown.com → tiktapdown-mcp) and Instagram is queued. The goal is a small family of per-platform MCP servers that share nothing but a common publishing pipeline and Docker base image.

If you're building your own MCP server, the fastest way to sanity-check the design is to install one that already works (mine or someone else's) and see what the tool calls actually look like from the LLM side. That gave me the biggest "oh, so that's how this fits together" moment early on.

Try it

Install: npx -y xtapdown-mcp
Config for Claude Desktop: full instructions
Source: github.com/farukkolip/xtapdown-mcp
npm: xtapdown-mcp
The web tools it wraps: xtapdown.com — free, no signup

Happy to answer any technical questions in the comments — especially about the syndication endpoint approach or any of the distribution channels above. If you're stuck on a publishing quirk I ran into, I probably have the fix in a scratch file somewhere.

DEV Community: Omer Faruk Kolip

I built an MCP server for Instagram — 16 tools, and everything the MCP publishing pipeline has quietly changed since my last one

The setup — same shape as before

What actually changed since XTapDown

1. server.json grew a transport field

2. mcp-publisher device tokens are short-lived

3. Glama's scoring is layered now, not just "gated by a Dockerfile"

4. Maintenance score has a floor for new repos — even with everything green

5. PulseMCP no longer has a submission form

The publishing sequence I'd run today, if I were shipping shipment #3

The bit that didn't need re-learning

What's next

Try instapdown-mcp

I built an MCP server for X (Twitter) — 14 tools in ~600 lines, here's what I learned

Why MCP over just having a REST API

The stack

The syndication endpoint trick

Publishing — this is where MCP gets weird

1. npm

2. Anthropic MCP Registry

3. Glama

4. awesome-mcp-servers

5. PulseMCP + mcp.so + others

Testing this thing

What I'd do differently

What's next

Try it

1. `server.json` grew a `transport` field

2. `mcp-publisher` device tokens are short-lived