Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 5 min read

How We Built a Remote 10-Tool Streamable HTTP MCP Server and 13.3 KiB Link-in-Bio in Go

Public link-in-bio pages are structurally simple documents: an avatar, a name, a contact bar, and 5 to 20 links. Yet most commercial bio-link platforms render them as client-heavy Single-Page Applications that download h

Public link-in-bio pages are structurally simple documents: an avatar, a name, a contact bar, and 5 to 20 links. Yet most commercial bio-link platforms render them as client-heavy Single-Page Applications that download hundreds of kilobytes of framework JavaScript inside Instagram, TikTok, or WhatsApp in-app WebViews before painting a button.

When we built Linq.es and its Official Remote MCP Server (https://linq.es/mcp), we took the opposite path on both the public frontend and the AI agent layer:

  1. Public profiles render server-side in Go (html/template) with inline critical CSS, 5.1 KiB of gzipped async CSS, 8.2 KiB of gzipped defer vanilla JS, and zero React, Next.js, or Vue runtime (13.3 KiB total gzipped first-party CSS + JS).
  2. AI agents connect directly to https://linq.es/mcp over Streamable HTTP (JSON-RPC 2.0, MCP spec 2025-03-26) using a Personal API Key (lnq_live_...), without installing a local npx or Python stdio wrapper.

Below are the main architectural lessons we learned building both layers in Go.

1. Why Go HTML SSR beats heavy SPA bundles inside social WebViews

Most link-in-bio clicks happen inside constrained mobile WebViews (Instagram, TikTok, LinkedIn, X, and WhatsApp) over variable cellular connections. Every extra script tag, font round-trip, and client hydration pass delays First Contentful Paint and increases bounce rates before a visitor taps a wa.me button or downloads a .vcf contact card.

On Linq.es, public profiles render complete semantic HTML in the European Union behind a multi-tier cache (in-memory L1, persistent object storage L2, and Cloudflare Edge CDN):

Async stylesheet:     ~5.1 KiB gzipped (loaded non-blocking)
Deferred vanilla JS:  ~8.2 KiB gzipped (loaded with defer)
Total external CSS+JS: 13.3 KiB gzipped (zero client SPA framework)

No third-party ad pixels (Meta, TikTok, or GA4) are injected on public pages unless a Pro profile owner explicitly configures their own measurement IDs.

2. Streamable HTTP MCP (2025-03-26) vs local stdio wrappers

Many early MCP integrations wrap an existing REST API inside a local Node.js stdio package that users run via npx -y @vendor/mcp-server. That introduces three recurring friction points:

  • Node or Python version mismatches on developer machines
  • Stale local npm packages when tool schemas or annotations evolve
  • No support on cloud, browser, or mobile MCP hosts that cannot spawn local subprocesses

With the 2025-03-26 Streamable HTTP specification, an MCP server runs as a standard HTTPS JSON-RPC 2.0 endpoint:

  • GET https://linq.es/mcp serves human-readable discovery metadata (name: "linqes-mcp", protocolVersion: "2025-03-26", transport: "streamable-http").
  • POST https://linq.es/mcp handles initialize, notifications/initialized, ping, tools/list, and authenticated tools/call executions.

Lesson #1: notifications/initialized must return 202 Accepted with an empty body

During the MCP handshake, right after initialize succeeds, strict clients send a JSON-RPC notification ({"jsonrpc": "2.0", "method": "notifications/initialized"}) that omits the id field. If your HTTP router wraps every return path in a 200 OK JSON-RPC envelope with "id": null, strict clients treat the unexpected body as a protocol error.

In Go + Gin, handling JSON-RPC notifications before dispatching methods keeps the handshake clean:

// JSON-RPC notifications omit "id" and must not return a JSON-RPC response body.
if strings.HasPrefix(req.Method, "notifications/") || len(req.ID) == 0 {
    c.Status(http.StatusAccepted)
    return
}

Lesson #2: Evict edge caches synchronously on serverless runtimes

On serverless container platforms, CPU allocation drops as soon as the HTTP response finishes writing. If an AI agent calls add_profile_link or update_profile_link and you trigger CDN cache purges in detached background goroutines, the container can be throttled before the outbound purge completes, leaving visitors looking at stale HTML when the agent reports the link is live.

Running storage and CDN cache invalidations concurrently inside a sync.WaitGroup before returning the tools/call response guarantees that by the time Claude or Cursor replies "Done, live at https://linq.es/handle", public visitors already see the updated page:

var wg sync.WaitGroup
wg.Add(2)
go func() {
    defer wg.Done()
    purgeObjectCache(ctx, profileHandle)
}()
go func() {
    defer wg.Done()
    purgeEdgeCDN(ctx, profileHandle)
}()
wg.Wait()

Lesson #3: Explicit MCP Tool Annotations (2025-03-26) matter for agent safety

When exposing read, write, and delete operations side by side, tool descriptions alone should not force an LLM host to guess which calls are safe to auto-approve and which require human confirmation.

Adding standard MCP annotations (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint) using explicit boolean pointers in Go ensures false values serialize cleanly instead of being dropped by omitempty:

type MCPToolAnnotations struct {
    Title           string `json:"title,omitempty"`
    ReadOnlyHint    *bool  `json:"readOnlyHint,omitempty"`
    DestructiveHint *bool  `json:"destructiveHint,omitempty"`
    IdempotentHint  *bool  `json:"idempotentHint,omitempty"`
    OpenWorldHint   *bool  `json:"openWorldHint,omitempty"`
}

Combined with "additionalProperties": false on every tool's inputSchema and clear prerequisite notes (e.g., calling list_profiles to discover handles and list_profile_links before update_profile_link or delete_profile_link), agents avoid hallucinating parameters or accidentally deleting links when a user only asked to hide one (active: false).

Connecting to https://linq.es/mcp

Once you generate a Personal API Key in Account Settings, you can connect Cursor (~/.cursor/mcp.json), Claude Desktop, Windsurf, or Gemini CLI (~/.gemini/settings.json) directly over HTTPS:

{
  "mcpServers": {
    "linqes": {
      "url": "https://linq.es/mcp",
      "headers": {
        "Authorization": "Bearer lnq_live_YOUR_PERSONAL_API_KEY"
      }
    }
  }
}

From there, your agent can use all 10 tools across up to 5 profiles and 500 /s/ shortlinks:

  • list_profiles: List owned profiles, themes, public URLs, and cumulative view counts.
  • get_profile_analytics: Pull 1-to-90-day views, clicks, CTR percentage, referrers, countries, devices, and daily time series.
  • list_profile_links: Inspect every link's key, url, active state, click count, and iOS/Android overrides.
  • add_profile_link: Publish a link or social icon with optional badgeText, iosUrl, androidUrl, scheduleStart/scheduleEnd (RFC3339), live countdown, or click badge.
  • update_profile_link & delete_profile_link: Edit, toggle (active: false), or permanently remove links with immediate cache invalidation.
  • import_bio_links: Migrate public links from an existing Linktree, Beacons, or Bio.link URL in one call.
  • list_shortlinks & create_shortlink: Create and audit https://linq.es/s/:code shortlinks with custom 3-50 character slugs, iOS/Android routing, and utm_source through utm_content tags.
  • list_leads: Retrieve recent Name, Email, and WhatsApp contacts captured via your profile's Lead Magnet form.

You can inspect the live discovery metadata anytime with curl -s https://linq.es/mcp | jq ., try the free .vcf, WhatsApp, and UTM generators without an account at https://linq.es/tools, or read the full MCP setup docs at https://linq.es/integrations/mcp.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.