<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Jeanmi</title>
    <description>The latest articles on DEV Community by Jeanmi (@jeanmi_3fbea472e70e4e377d).</description>
    <link>https://dev.to/jeanmi_3fbea472e70e4e377d</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4217602%2F0472bfed-b3db-4885-b620-7d80e348d25e.jpg</url>
      <title>DEV Community: Jeanmi</title>
      <link>https://dev.to/jeanmi_3fbea472e70e4e377d</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/jeanmi_3fbea472e70e4e377d"/>
    <language>en</language>
    <item>
      <title>Server-side Facebook and Instagram ad tracking without GTM, with consent built in</title>
      <dc:creator>Jeanmi</dc:creator>
      <pubDate>Fri, 20 Nov 2026 21:44:54 +0000</pubDate>
      <link>https://dev.to/jeanmi_3fbea472e70e4e377d/server-side-facebook-and-instagram-ad-tracking-without-gtm-with-consent-built-in-12e1</link>
      <guid>https://dev.to/jeanmi_3fbea472e70e4e377d/server-side-facebook-and-instagram-ad-tracking-without-gtm-with-consent-built-in-12e1</guid>
      <description>&lt;p&gt;If you run Facebook or Instagram ads, you've probably been told to "add the Conversions API". The browser Pixel misses conversions: ad blockers, Safari's tracking limits and tabs closed too early all drop events before they reach Meta. Meta's answer is to send the same events from your server too.&lt;/p&gt;

&lt;p&gt;The usual path is a server-side Google Tag Manager container, often on a paid host. That works, but it's a lot of machinery if all you want is to send a few conversion events from your site and backend.&lt;/p&gt;

&lt;p&gt;This post covers what any Conversions API setup has to get right, with code, and then shows a small open-source relay I wrote that does it in one service.&lt;/p&gt;

&lt;h2&gt;
  
  
  The five things you have to get right
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. Deduplication: one conversion, one count
&lt;/h3&gt;

&lt;p&gt;If the Pixel and your server both report a purchase, Meta needs to know it's the same purchase. The rule is simple: &lt;strong&gt;send the same &lt;code&gt;event_id&lt;/code&gt; from both sides&lt;/strong&gt;, along with the same &lt;code&gt;event_name&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;eventId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;crypto&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;randomUUID&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Browser&lt;/span&gt;
&lt;span class="nf"&gt;fbq&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'track'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'Purchase'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;49.90&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'EUR'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;eventID&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;eventId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Server (same id)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;event_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'Purchase'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;event_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;eventId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Forget this and your conversions are counted twice, which quietly wrecks your cost-per-result numbers.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Hashing, with Meta's normalization rules
&lt;/h3&gt;

&lt;p&gt;Contact data (&lt;code&gt;em&lt;/code&gt;, &lt;code&gt;ph&lt;/code&gt;, &lt;code&gt;fn&lt;/code&gt;, &lt;code&gt;ln&lt;/code&gt;, &lt;code&gt;ct&lt;/code&gt;, &lt;code&gt;zp&lt;/code&gt;, &lt;code&gt;db&lt;/code&gt;, &lt;code&gt;external_id&lt;/code&gt;…) must be &lt;strong&gt;normalized, then SHA-256 hashed&lt;/strong&gt;. The normalization is where most homemade implementations go wrong:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;emails: trim and lowercase, so &lt;code&gt;Jane@Example.com&lt;/code&gt; becomes &lt;code&gt;jane@example.com&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;phones: digits only, &lt;strong&gt;with the country code&lt;/strong&gt;, so &lt;code&gt;06 12 34 56 78&lt;/code&gt; (France) becomes &lt;code&gt;33612345678&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;names: lowercase, no punctuation, no spaces;&lt;/li&gt;
&lt;li&gt;dates of birth: &lt;code&gt;YYYYMMDD&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Some fields must &lt;strong&gt;not&lt;/strong&gt; be hashed: &lt;code&gt;client_ip_address&lt;/code&gt;, &lt;code&gt;client_user_agent&lt;/code&gt;, &lt;code&gt;fbp&lt;/code&gt; and &lt;code&gt;fbc&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. &lt;code&gt;fbp&lt;/code&gt; and &lt;code&gt;fbc&lt;/code&gt; for match quality
&lt;/h3&gt;

&lt;p&gt;The Pixel stores two first-party cookies: &lt;code&gt;_fbp&lt;/code&gt; (the browser) and &lt;code&gt;_fbc&lt;/code&gt; (the ad click). Sending them with server events improves how well Meta matches your events to people. If &lt;code&gt;_fbc&lt;/code&gt; isn't set yet but the URL has an &lt;code&gt;fbclid&lt;/code&gt; parameter, you can build it: &lt;code&gt;fb.1.&amp;lt;timestamp&amp;gt;.&amp;lt;fbclid&amp;gt;&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Consent
&lt;/h3&gt;

&lt;p&gt;This is the one many vendors skip. Moving tracking to the server &lt;strong&gt;does not remove the need for consent&lt;/strong&gt; in the EU and UK. If the visitor refused marketing cookies, the event shouldn't go to Meta at all, from the browser or from your server.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. Reliability
&lt;/h3&gt;

&lt;p&gt;The Conversions API rejects events older than 7 days, rejects a whole batch if one event is invalid, and sometimes returns transient errors. You need a queue, retries with backoff, and a way to isolate the one bad event so it doesn't block the others.&lt;/p&gt;

&lt;h2&gt;
  
  
  A relay that does all of that
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://jean82290.github.io/capi-relay/" rel="noopener noreferrer"&gt;CAPI Relay&lt;/a&gt; is a small open-source (MIT) Node.js service, with one dependency and a Postgres database, that sits between your site and the Conversions API.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;browser (Pixel + capi.js) ──▶ CAPI Relay ──▶ Meta Conversions API
your backend ──POST /v1/events──▶   │
                         consent · hashing · dedup · queue · retries
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  On your website
&lt;/h3&gt;

&lt;p&gt;Load the helper after your Pixel:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;script&amp;gt;&lt;/span&gt;
  &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;capi&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;capi&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;capi&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;q&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;capi&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;q&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;arguments&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/script&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;script&lt;/span&gt; &lt;span class="na"&gt;async&lt;/span&gt; &lt;span class="na"&gt;src&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"https://t.myshop.com/capi.js"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&amp;lt;/script&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;From your cookie banner, once the visitor accepts marketing cookies:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;capi&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'consent'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// and capi('consent', false) if they withdraw it&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then use &lt;code&gt;capi('track', …)&lt;/code&gt; instead of &lt;code&gt;fbq('track', …)&lt;/code&gt;. It fires the Pixel &lt;strong&gt;and&lt;/strong&gt; the relay with the same event ID:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="nf"&gt;capi&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'track'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'Purchase'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;49.90&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;currency&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'EUR'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;userData&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;em&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'jane@example.com'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ph&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'06 12 34 56 78'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;eventId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'order-1042'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Until consent is granted, the helper sends nothing, not even to the relay. It never sets cookies; it only reads &lt;code&gt;_fbp&lt;/code&gt;/&lt;code&gt;_fbc&lt;/code&gt; and builds &lt;code&gt;fbc&lt;/code&gt; from &lt;code&gt;fbclid&lt;/code&gt; when needed.&lt;/p&gt;

&lt;h3&gt;
  
  
  From your backend
&lt;/h3&gt;

&lt;p&gt;For order confirmations, CRM updates or offline sales:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -X POST https://t.myshop.com/v1/events \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $API_KEY"&lt;/span&gt; \
  -H &lt;span class="s2"&gt;"Content-Type: application/json"&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"events":[{"event_name":"Purchase","event_id":"order-1042","consent":true,
       "event_source_url":"https://www.myshop.com/checkout",
       "user_data":{"em":"jane@example.com","client_ip_address":"203.0.113.7","client_user_agent":"Mozilla/5.0 …"},
       "custom_data":{"value":49.9,"currency":"EUR"}}]}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each event must say &lt;code&gt;"consent": true&lt;/code&gt;; events without it are dropped and never stored.&lt;/p&gt;

&lt;h3&gt;
  
  
  What happens inside
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Hashing on arrival&lt;/strong&gt;, before anything touches the database, following Meta's normalization rules. Values already hashed are passed through.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deduplication&lt;/strong&gt;: the same &lt;code&gt;event_name&lt;/code&gt; + &lt;code&gt;event_id&lt;/code&gt; is accepted once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A durable Postgres queue&lt;/strong&gt; with exponential backoff. An invalid batch is split until the bad event is isolated, so the others still go through.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Expiry&lt;/strong&gt;: events that would be older than 7 days are marked expired instead of being retried forever.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Short retention&lt;/strong&gt;: stored events are deleted after 7 days by default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Browser endpoint locked down&lt;/strong&gt;: CORS limited to your own sites, plus rate limiting.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  A dashboard that tells you what's wrong
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;/admin&lt;/code&gt; (password-protected) shows the delivery rate, the queue, events dropped for lack of consent, duplicates, and Meta's own error messages. If your token is wrong, you see "Invalid OAuth access token" right there, and events wait in the queue until you fix it. A button sends a test event to Events Manager's &lt;em&gt;Test events&lt;/em&gt; tab.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploying it
&lt;/h2&gt;

&lt;p&gt;It's a plain Dockerfile, so it runs anywhere you can run a container with Postgres. There's also a one-click &lt;a href="https://railway.com/deploy/xSo6oY" rel="noopener noreferrer"&gt;Railway template&lt;/a&gt; that sets up the relay, Postgres over the private network, and generated secrets.&lt;/p&gt;

&lt;p&gt;You need three values:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;code&gt;META_PIXEL_ID&lt;/code&gt;: your dataset (Pixel) ID from Events Manager.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;META_ACCESS_TOKEN&lt;/code&gt;: Events Manager → your dataset → Settings → Conversions API → &lt;em&gt;Generate access token&lt;/em&gt;. No Meta app review is needed.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ALLOWED_ORIGINS&lt;/code&gt;: your site, for example &lt;code&gt;https://www.myshop.com&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Then put the relay on a subdomain of your site (&lt;code&gt;t.myshop.com&lt;/code&gt;), so the browser sends the Pixel's first-party cookies to it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before going live
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Make sure your Pixel itself only loads after consent, and that your banner calls &lt;code&gt;capi('consent', …)&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Mention the Conversions API in your privacy policy.&lt;/li&gt;
&lt;li&gt;Don't send sensitive data (health, for example). Meta's Business Tools Terms forbid it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Links
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Documentation: &lt;a href="https://jean82290.github.io/capi-relay/" rel="noopener noreferrer"&gt;jean82290.github.io/capi-relay&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Source (MIT): &lt;a href="https://github.com/jean82290/capi-relay" rel="noopener noreferrer"&gt;github.com/jean82290/capi-relay&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Meta's docs: &lt;a href="https://developers.facebook.com/docs/marketing-api/conversions-api" rel="noopener noreferrer"&gt;Conversions API&lt;/a&gt;, &lt;a href="https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events" rel="noopener noreferrer"&gt;deduplication&lt;/a&gt;, &lt;a href="https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters" rel="noopener noreferrer"&gt;customer information parameters&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Disclosure: I'm the author of CAPI Relay. If you deploy it through the Railway template, I receive a share of Railway's hosting fees; running it from the Dockerfile costs me nothing. Not affiliated with Meta. "Facebook" and "Instagram" are trademarks of Meta Platforms, Inc.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Questions or feedback are welcome in the comments or on GitHub.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>opensource</category>
      <category>privacy</category>
      <category>javascript</category>
    </item>
    <item>
      <title>Give Claude Code and Cursor a shared, auto-updating map of your codebase</title>
      <dc:creator>Jeanmi</dc:creator>
      <pubDate>Fri, 30 Oct 2026 15:47:19 +0000</pubDate>
      <link>https://dev.to/jeanmi_3fbea472e70e4e377d/give-claude-code-and-cursor-a-shared-auto-updating-map-of-your-codebase-4b59</link>
      <guid>https://dev.to/jeanmi_3fbea472e70e4e377d/give-claude-code-and-cursor-a-shared-auto-updating-map-of-your-codebase-4b59</guid>
      <description>&lt;p&gt;AI coding assistants are great at writing code and surprisingly bad at knowing &lt;em&gt;where things are&lt;/em&gt;. Ask "what breaks if I change this function?" on a large repository and the assistant starts opening files one by one, burning tokens and context, and often still misses a caller three modules away.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/Graphify-Labs/graphify" rel="noopener noreferrer"&gt;Graphify&lt;/a&gt; fixes that by turning a codebase into a knowledge graph: functions, classes, modules and the edges between them, parsed locally with tree-sitter. Your assistant queries the graph through MCP instead of re-reading the code. With over 130k GitHub stars, it clearly hit a nerve.&lt;/p&gt;

&lt;p&gt;This post shows how to run Graphify as &lt;strong&gt;one shared MCP server&lt;/strong&gt; that every assistant on your team can use, kept up to date automatically. Everything here is open source.&lt;/p&gt;

&lt;h2&gt;
  
  
  Local graph vs. shared server
&lt;/h2&gt;

&lt;p&gt;The default Graphify workflow is local: you run it in your repo, it writes &lt;code&gt;graphify-out/graph.json&lt;/code&gt;, and your assistant reads it. If you work alone on one machine, that's perfect. Committing &lt;code&gt;graphify-out/&lt;/code&gt; and installing Graphify's git hook even keeps several of your own machines in sync.&lt;/p&gt;

&lt;p&gt;It gets clumsier when:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;several people (or several agents) need the same graph,&lt;/li&gt;
&lt;li&gt;you don't want everyone to install and run Graphify locally,&lt;/li&gt;
&lt;li&gt;you want the graph to follow &lt;code&gt;main&lt;/code&gt; without anyone thinking about it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Graphify already ships an HTTP transport for its MCP server, so the missing piece is just the plumbing: clone, build, serve, refresh, secure. That's what &lt;a href="https://github.com/jean82290/graphify-railway" rel="noopener noreferrer"&gt;graphify-railway&lt;/a&gt; does.&lt;/p&gt;

&lt;h2&gt;
  
  
  How it works
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;your Git repo ──clone/pull──▶ graphify extract --code-only ──▶ graph.json (volume)
                                                                   │ reloaded on change
Claude Code / Cursor ──HTTPS + API key──▶ /mcp ◀── graphify.serve --transport http
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Clone.&lt;/strong&gt; On start, the service clones &lt;code&gt;REPO_URL&lt;/code&gt;. Private repos work with a read-only token.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Build.&lt;/strong&gt; It runs &lt;code&gt;graphify extract --code-only&lt;/code&gt;: pure local AST parsing, no LLM API key. On a small repo (about 100 nodes) it takes under a second.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Serve.&lt;/strong&gt; It starts &lt;code&gt;graphify.serve&lt;/code&gt; over MCP Streamable HTTP on &lt;code&gt;/mcp&lt;/code&gt;. Every request must carry the API key.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Refresh.&lt;/strong&gt; Every hour (configurable), it pulls the repo. If the commit changed, it rebuilds and swaps &lt;code&gt;graph.json&lt;/code&gt; atomically. Graphify's server checks the file on each request and reloads it, so connected clients keep their session: no restart, no downtime.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;A few details I cared about:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The git token never touches the disk.&lt;/strong&gt; It's passed to each git command as an HTTP header, not written to &lt;code&gt;.git/config&lt;/code&gt;, and it's redacted from logs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The API key isn't on the command line.&lt;/strong&gt; It goes through the environment, so it doesn't show up in &lt;code&gt;ps&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The last good graph survives.&lt;/strong&gt; It lives on a persistent volume: if the repo is briefly unreachable at startup, the previous graph is served; if a refresh fails, the old graph stays online.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Graphify is pinned&lt;/strong&gt; to a tested release in the Dockerfile. Graphify ships very often, and you don't want a surprise upgrade on a team server.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The whole wrapper is one Python file and a Dockerfile.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deploy it
&lt;/h2&gt;

&lt;h3&gt;
  
  
  One click on Railway
&lt;/h3&gt;

&lt;p&gt;&lt;a href="https://railway.com/deploy/graphify-or-team-mcp-server-with-auto-up" rel="noopener noreferrer"&gt;Deploy on Railway&lt;/a&gt;. You get the service and a volume. Fill in one variable, &lt;code&gt;REPO_URL&lt;/code&gt; (for example &lt;code&gt;https://github.com/your-org/your-repo&lt;/code&gt;); the API key is generated for you. For a private repo, also set &lt;code&gt;GIT_TOKEN&lt;/code&gt;. On GitHub, use a fine-grained token limited to that repository with &lt;strong&gt;Contents: Read-only&lt;/strong&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Anywhere you can run a container
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker build &lt;span class="nt"&gt;-t&lt;/span&gt; graphify-server https://github.com/jean82290/graphify-railway.git

docker run &lt;span class="nt"&gt;-d&lt;/span&gt; &lt;span class="nt"&gt;-p&lt;/span&gt; 8080:8080 &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-v&lt;/span&gt; graphify-data:/data &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="nv"&gt;REPO_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;https://github.com/your-org/your-repo &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="nv"&gt;GRAPHIFY_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;openssl rand &lt;span class="nt"&gt;-hex&lt;/span&gt; 24&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  graphify-server
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Put it behind HTTPS before sharing it with anyone.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Required&lt;/th&gt;
&lt;th&gt;Default&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;REPO_URL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;HTTPS URL of the repository to map&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GRAPHIFY_API_KEY&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;Key every MCP client must send&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GIT_TOKEN&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;private repos&lt;/td&gt;
&lt;td&gt;&lt;/td&gt;
&lt;td&gt;Read-only access token&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;REPO_BRANCH&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;default branch&lt;/td&gt;
&lt;td&gt;Branch to map&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;REFRESH_MINUTES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;&lt;code&gt;60&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;How often to pull and rebuild (&lt;code&gt;0&lt;/code&gt; disables)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Connect your assistant
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Claude Code:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude mcp add &lt;span class="nt"&gt;--transport&lt;/span&gt; http graphify https://YOUR-SERVICE.up.railway.app/mcp &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;--header&lt;/span&gt; &lt;span class="s2"&gt;"Authorization: Bearer YOUR_GRAPHIFY_API_KEY"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Cursor&lt;/strong&gt; (&lt;code&gt;.cursor/mcp.json&lt;/code&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"mcpServers"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"graphify"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"https://YOUR-SERVICE.up.railway.app/mcp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"headers"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"Authorization"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Bearer YOUR_GRAPHIFY_API_KEY"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Any MCP client that supports Streamable HTTP with custom headers works the same way.&lt;/p&gt;

&lt;h2&gt;
  
  
  What your assistant can do with it
&lt;/h2&gt;

&lt;p&gt;Graphify exposes tools such as &lt;code&gt;query_graph&lt;/code&gt;, &lt;code&gt;get_node&lt;/code&gt;, &lt;code&gt;get_neighbors&lt;/code&gt;, &lt;code&gt;get_community&lt;/code&gt;, &lt;code&gt;god_nodes&lt;/code&gt;, &lt;code&gt;graph_stats&lt;/code&gt; and &lt;code&gt;shortest_path&lt;/code&gt;, plus PR-oriented tools (&lt;code&gt;list_prs&lt;/code&gt;, &lt;code&gt;get_pr_impact&lt;/code&gt;, &lt;code&gt;triage_prs&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;In practice, this means questions like these get answered from the graph instead of a file-by-file crawl:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;"What calls &lt;code&gt;buildEvent&lt;/code&gt;, directly or indirectly?"&lt;/li&gt;
&lt;li&gt;"What's the shortest path between the HTTP handler and the database layer?"&lt;/li&gt;
&lt;li&gt;"Which parts of the code are the most connected, and therefore the riskiest to change?"&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When I tested it on a small Node.js project, a &lt;code&gt;query_graph&lt;/code&gt; call starting from one function returned its 80 related nodes and 152 edges in a single response. That's the context an assistant would otherwise have to rebuild by opening a dozen files.&lt;/p&gt;

&lt;h2&gt;
  
  
  Security notes
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;The server is reachable on the internet, and &lt;strong&gt;the API key is what keeps your code map private&lt;/strong&gt;. Rotate it by changing &lt;code&gt;GRAPHIFY_API_KEY&lt;/code&gt; and redeploying.&lt;/li&gt;
&lt;li&gt;The graph contains names and relationships from your code, not the full source, but treat it as confidential if your code is.&lt;/li&gt;
&lt;li&gt;Use a token with read access to a single repository.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Limitations
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Code only, for now.&lt;/strong&gt; Graphify can also extract docs, PDFs and images, but that pass needs an LLM backend and an API key. The wrapper sticks to the free, offline AST mode.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One repository per instance.&lt;/strong&gt; If you need several, run several instances (or tell me you'd like multi-repo support).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hourly refresh by default.&lt;/strong&gt; Lower &lt;code&gt;REFRESH_MINUTES&lt;/code&gt; if you need fresher graphs.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Links
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Source (MIT): &lt;a href="https://github.com/jean82290/graphify-railway" rel="noopener noreferrer"&gt;github.com/jean82290/graphify-railway&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;One-click deploy: &lt;a href="https://railway.com/deploy/graphify-or-team-mcp-server-with-auto-up" rel="noopener noreferrer"&gt;Railway template&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Graphify itself (Apache-2.0): &lt;a href="https://github.com/Graphify-Labs/graphify" rel="noopener noreferrer"&gt;github.com/Graphify-Labs/graphify&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Disclosure: this is an unofficial wrapper, not affiliated with Graphify Labs. If you deploy through the Railway template, I receive a share of Railway's hosting fees. The Docker route above costs me nothing and works just as well.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Questions, ideas or bugs: open an issue on GitHub or leave a comment below. I'm especially curious whether multi-repo support would be useful to you.&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>ai</category>
      <category>opensource</category>
      <category>productivity</category>
    </item>
  </channel>
</rss>
