Tag: Automation

  • Logic Apps vs Cloud Workflows: No-Code Automation Across Two Clouds

    Logic Apps vs Cloud Workflows: No-Code Automation Across Two Clouds

    Every content operation runs on small invisible chains of “when this happens, do that.” Publish an article → notify a channel → write a row to the ledger. None of it is hard, but you don’t want to babysit a script for it — you want a managed orchestrator that fires on an event, calls a few services, and logs the result, for free. Azure and Google each have one, and they take opposite philosophies to the same job.

    We wire the same publish → notify → log automation on both Azure Logic Apps and Google Cloud Workflows, on the free tiers, and compare. Short answer: Logic Apps wins when the work is gluing SaaS services together — its connector library and visual designer are unmatched, with a free grant of 4,000 built-in actions/month. Cloud Workflows wins when the work is lightweight, code-first orchestration inside GCP — its 5,000 internal + 2,000 external steps/month free tier pairs cleanly with Eventarc and Pub/Sub. One is a no-code SaaS glue gun; the other is a YAML orchestration engine.

    This is the breakdown from the running lab on tygart.media — connector ecosystems, visual designer vs YAML, triggers, and free ceilings.

    The free-tier ceilings

    How we do it

    Azure Google Cloud Verdict
    Free grant/month 4,000 built-in actions 5,000 internal + 2,000 external steps Comparable, units differ
    Billing model Per-action (Consumption) Per-step (internal vs external) Different mental models
    What counts Each connector/built-in action Each workflow step executed Tie at our volume
    Fit for a glue chain Generous Generous Tie
    Our actual bill $0 $0 Tie where it counts

    Both free grants comfortably cover a real automation cadence. A publish → notify → log chain is three or four actions/steps per run; at a few publishes a day, neither 4,000 actions nor 7,000 steps comes close to binding. The units differ — Azure counts actions, Workflows splits internal vs external steps (external = calls out to other services, which are scarcer) — but for our workload both run free.

    Connectors vs code-first

    This is the real fork in the road, and it decides the choice.

    How we do it

    Azure Google Cloud Verdict
    Connector library Hundreds (SaaS + Microsoft + 3rd-party) HTTP + GCP services, no big SaaS catalog Logic Apps, decisively
    Authoring model Visual designer (drag-and-drop) YAML (code-first) Logic Apps for no-code
    SaaS glue (Slack, email, etc.) Native connectors, prebuilt auth Roll your own via HTTP Logic Apps
    GCP-native orchestration Possible via HTTP First-class Cloud Workflows
    Versioning / review in git Exportable, but designer-first YAML lives in git naturally Cloud Workflows

    Logic Apps’ superpower is its connector library — hundreds of prebuilt, pre-authenticated connectors for Slack, Office, Salesforce, Twitter/X, databases, and most SaaS you’d name. Wiring “post to Slack when an article publishes” is point-and-click, with the OAuth handled for you. Cloud Workflows takes the opposite stance: it’s code-first YAML with no big SaaS catalog — you orchestrate GCP services and arbitrary HTTP endpoints, building any integration you need by hand. That’s less convenient for SaaS glue but cleaner for engineers who want their orchestration in git, reviewed like code.

    Triggers and event sources

    How we do it

    Azure Google Cloud Verdict
    Native triggers Many (HTTP, schedule, connector events) HTTP + Eventarc/Pub/Sub Logic Apps on built-in variety
    Event-driven on cloud events Via Event Grid Via Eventarc (first-class) Cloud Workflows for GCP events
    Schedule / cron Built-in recurrence Cloud Scheduler Tie
    SaaS event triggers Connector-based, prebuilt Roll your own Logic Apps
    Pub/Sub-style fan-out Event Grid Pub/Sub (native pairing) Cloud Workflows in GCP

    Logic Apps can be triggered by connector events directly — “when a new email arrives,” “when a row is added” — which keeps SaaS-driven automations entirely no-code. Cloud Workflows leans on Eventarc and Pub/Sub for event sources, which is the idiomatic, powerful path if your events originate in GCP. Each is strongest for events native to its own cloud.

    What surprised us

    • Logic Apps’ connector library is the whole ballgame for SaaS glue. Pre-authenticated connectors turned a “write a small integration” task into a five-minute drag-and-drop. Nothing on the GCP side matches that catalog.
    • Cloud Workflows’ YAML-in-git is quietly the better engineering experience. When the orchestration lives in the repo and gets code-reviewed, it stops being a clickable black box. We liked that more than expected.
    • The free grants are both ample. We worried about per-action metering and never came near either ceiling at a realistic publishing cadence.
    • External steps are the scarce currency on GCP. Workflows’ 2,000 external steps (calls out to other services) is the limit to watch, not the 5,000 internal steps.

    The takeaway

    Pick Azure Logic Apps if your automation is mostly gluing SaaS services together — Slack, email, CRMs, Microsoft 365 — and you want a visual, no-code designer with hundreds of pre-authenticated connectors. It’s the fastest path from “I wish X notified Y” to a running flow.

    Pick Google Cloud Workflows if your automation is lightweight orchestration inside GCP — coordinating Cloud Run, Functions, Pub/Sub, and HTTP endpoints — and you want it defined as code-first YAML that lives in git and pairs with Eventarc. It’s the cleaner engineering primitive when the events and services are already on Google’s side.

    For our publish → notify → log chain, the deciding factor is where the notify lands: a Slack or email notification leans Logic Apps for the free connector; a fan-out into Cloud Run or Pub/Sub leans Workflows. Running the same chain on both made the connector-vs-code-first trade concrete.

    This is part of our “Two Clouds, One Site” series — we run the same media property on both Azure and Google Cloud on the free tiers, wiring the same automation on each to see which orchestrator fits which job. The lab lives on tygart.media; the findings publish here.

    Frequently asked questions

    What’s the free tier for Azure Logic Apps and Google Cloud Workflows?
    Azure Logic Apps (Consumption) includes a free grant of 4,000 built-in actions per month. Google Cloud Workflows includes 5,000 internal steps and 2,000 external steps per month free. Both comfortably cover a realistic automation cadence, so a small glue chain runs at $0 on either.

    Which is better for no-code automation, Logic Apps or Cloud Workflows?
    Logic Apps is the no-code choice — it has a visual drag-and-drop designer and hundreds of pre-authenticated connectors for SaaS services. Cloud Workflows is code-first YAML with no big SaaS catalog, so it suits engineers orchestrating GCP services rather than non-developers gluing apps together.

    Does Cloud Workflows have a connector library like Logic Apps?
    No. Cloud Workflows orchestrates GCP services and arbitrary HTTP endpoints, but it has no large prebuilt SaaS connector catalog the way Logic Apps does. To integrate a third-party SaaS in Workflows, you call its HTTP API and handle authentication yourself, whereas Logic Apps provides a ready-made connector.

    How do I trigger automation when an article is published?
    On Azure, a Logic App can be triggered by an HTTP request, a schedule, or a connector event, then call further connectors with no code. On Google Cloud, a Workflow is typically triggered via Eventarc or Pub/Sub for cloud-native events, or by HTTP. Each is strongest for events that originate inside its own cloud.

    Which is better for gluing SaaS and cloud events together?
    Logic Apps wins for SaaS glue thanks to its connector library and visual designer, making things like “notify Slack when X happens” nearly code-free. Cloud Workflows wins for lightweight, code-first orchestration of GCP services that lives in git and pairs with Eventarc and Pub/Sub. Pick by where your events and services already live.

  • Azure Neural TTS vs Google Cloud Text-to-Speech: Audio Versions of Every Article

    Azure Neural TTS vs Google Cloud Text-to-Speech: Audio Versions of Every Article

    Adding an audio version of every article is one of those low-effort, high-leverage moves: it makes your content accessible to people who’d rather listen, it gives you a “play this article” widget that lifts time-on-page, and the audio file itself becomes another thing search and assistants can surface. The work is entirely automated — text goes in, an MP3 comes out — so the only real decisions are which voice sounds least like a robot and which free tier covers your back catalog.

    We auto-generate audio versions of the same articles on both Azure Neural TTS and Google Cloud Text-to-Speech, on the free tiers, and listen. Short answer: this one’s an honest toss-up. Both produce genuinely natural neural voices, both give you SSML control, and both run our audio pipeline for $0/month. Azure’s free tier is 500,000 characters/month (~60–80 article audio versions of neural voices); Google’s is 1,000,000 characters/month of Standard voices and 1,000,000 characters/month of WaveNet/Neural2 premium voices. Pick by ecosystem and by which voice you’d rather hear.

    This is the breakdown from the running lab on tygart.media — voice naturalness, SSML control, voice variety, free ceilings, and the accessibility/SEO payoff.

    The free-tier ceilings

    How we do it

    Azure Google Cloud Verdict
    Free neural/premium chars/month 500,000 (Neural) 1,000,000 (WaveNet/Neural2) Google — 2× headroom
    Free standard chars/month n/a (neural is the tier) 1,000,000 (Standard) Google on raw volume
    Roughly how many article audios ~60–80 neural/mo ~140 premium/mo Google
    Always-free Yes Yes Tie
    Our actual bill $0 $0 Tie where it counts

    A 1,200-word article runs around 6,500–7,000 characters, so Azure’s 500K neural budget covers roughly 60–80 full article audio versions a month, and Google’s 1M premium budget covers roughly twice that. For a publisher shipping a handful of articles a week, both stay free with room to spare — the 2× gap only bites if you’re voicing a large back catalog in one go.

    Voice quality and SSML control

    This is where you actually choose, and it’s genuinely close.

    How we do it

    Azure Google Cloud Verdict
    Voice naturalness Excellent, very expressive Excellent, very natural Tie — both clear the “robot” bar
    Voice variety Huge neural catalog, many styles Large WaveNet/Neural2 catalog Slight edge Azure on styles
    Speaking styles / emotion Yes (cheerful, newscast, etc.) More limited emotional styles Azure
    SSML control Full SSML + style/prosody tags Full SSML Azure, slightly
    Custom voice Yes (custom neural voice) Yes (custom voice) Tie
    Languages / locales 140+ locales 50+ languages, many voices Azure on locale breadth

    Both clear the bar that matters: neither sounds like a 2010-era text-to-speech engine, and a casual listener wouldn’t immediately clock either as synthetic. Azure edges ahead on expressiveness — its neural voices support named speaking styles (newscast, cheerful, empathetic) that are perfect for an article read-aloud, and its SSML supports fine prosody control. Google’s Neural2 voices are beautifully natural and, to some ears, a touch warmer; the emotional-style controls are just a little thinner.

    The accessibility and SEO payoff

    The audio isn’t only a nice-to-have. It does real work.

    How we do it

    Azure Google Cloud Verdict
    Accessibility win Listen instead of read Listen instead of read Tie
    Output format MP3 / WAV / streaming MP3 / LINEAR16 / OGG Tie
    Pipeline integration REST + SDKs REST + SDKs Tie
    Time-on-page lift Audio widget keeps people on page Same Tie

    An audio version gives screen-reader users and “I’d rather listen” users a first-class way to consume the piece, and the on-page player tends to lift dwell time — a signal that doesn’t hurt. The mechanics are identical on both clouds: feed text, get an MP3, embed it.

    What surprised us

    • Both are genuinely good now. We expected one to clearly win on naturalness and neither did — the synthetic-voice era is over on both clouds.
    • Azure’s speaking styles are the sleeper feature. Being able to render an article in a “newscast” or “cheerful” style without writing prosody by hand made the read-alouds noticeably more engaging.
    • Google’s free character budget is the bigger one. 1M premium characters is real headroom; if you’re voicing a back catalog, that matters more than a half-point of naturalness.
    • The MP3s are interchangeable. Once embedded, listeners couldn’t reliably tell which cloud voiced which article in a blind test we ran on ourselves.

    The takeaway

    Pick Azure Neural TTS if you want maximum expressiveness — named speaking styles, fine prosody control, and the broadest locale catalog — and your Microsoft ecosystem is already where the rest of your stack lives. The 500K free characters cover a normal publishing cadence comfortably.

    Pick Google Cloud Text-to-Speech if you want the larger free character budget (1M premium) for voicing a big back catalog, or you simply prefer the warmth of the Neural2 voices, and your stack is GCP-centric.

    For us this is the rare comparison with no loser. We run the pipeline on whichever cloud the rest of that article’s workflow already lives on — and the listener can’t tell the difference either way.

    This is part of our “Two Clouds, One Site” series — we run the same media property on both Azure and Google Cloud on the free tiers, generating audio versions of the same articles on each to hear where the voices differ. The lab lives on tygart.media; the findings publish here.

    Frequently asked questions

    How many free characters do Azure and Google text-to-speech give you per month?
    Azure Neural TTS gives 500,000 free neural characters per month, which is roughly 60–80 article audio versions. Google Cloud Text-to-Speech gives 1,000,000 free Standard characters and 1,000,000 free WaveNet/Neural2 premium characters per month, roughly double Azure’s premium headroom. Both stay free for a normal publishing cadence.

    Which text-to-speech sounds more natural, Azure or Google?
    Both produce genuinely natural neural voices, and in blind listening neither clearly wins. Azure edges ahead on expressiveness with named speaking styles like newscast and cheerful, while Google’s Neural2 voices are very natural and, to some ears, slightly warmer. The synthetic-robot problem is solved on both.

    Can I auto-generate an audio version of every blog post for free?
    Yes. Both clouds expose a simple REST API that turns article text into an MP3, and their free character budgets cover a typical few-articles-a-week cadence at $0. Google’s larger free budget is better if you want to voice a big back catalog in one pass.

    Does Azure Neural TTS support SSML and speaking styles?
    Yes. Azure supports full SSML plus named speaking styles (newscast, cheerful, empathetic and more) and fine prosody control, which makes article read-alouds noticeably more engaging. Google also supports full SSML, but its emotional-style controls are thinner.

    Does adding an audio version of articles help accessibility and SEO?
    Yes. An audio version gives screen-reader and listen-first users a first-class way to consume the content, improving accessibility, and the on-page audio player tends to lift time-on-page, which is a positive engagement signal. The benefit is identical whether you generate the audio on Azure or Google.

  • Azure Functions vs Cloud Run: We Ran the Same Worker on Both

    Pick a serverless platform and you’re picking a default for the next five years of your stack. Most comparisons of Azure Functions vs Google Cloud Run are written from the docs. This one isn’t — we deployed the same worker to both, in production, on the free tiers, and watched what happened.

    The worker is simple on purpose: it takes a webhook, does a little work, writes a record, returns JSON. The kind of glue every real system has dozens of. Boring is exactly what you want when you’re measuring the platform and not the app.

    The short answer

    If you just want the verdict: Cloud Run wins for anything containerized and anything where you care about not storing deploy keys. Azure Functions wins when your automation already lives in the Microsoft ecosystem and benefits from Logic Apps, Event Grid, and Entra sitting right next door. Both run our worker for $0/month. The tie-breakers are deploy security and what else is in the neighborhood.

    Now the detail.

    Deploying the same worker

    This is where the two platforms feel most different, and where Google Cloud quietly pulls ahead.

    How we do it

    Azure Functions Google Cloud Run Verdict
    Unit of deploy Function app (code + host) Container image Cloud Run if you’re already containerized
    Deploy auth Publish profile / service principal Workload Identity Federation — no stored keys Cloud Run, decisively
    Cold start Noticeable on Consumption plan Negligible at our scale Cloud Run
    Local dev parity Functions Core Tools (good) “It’s just a container” (great) Cloud Run

    The headline is the deploy auth. Our Cloud Run workers deploy from GitHub Actions using Workload Identity Federation — GitHub proves its identity to Google with a short-lived token, and no service-account key is ever stored in the repo. That’s not a convenience; it’s the single biggest reduction in credential risk you can make in a CI/CD pipeline. Azure Functions can get close with OIDC + a service principal, but the container-native, keyless Cloud Run path was simpler to lock down and is the model we standardized on.

    What the free tier actually gives you

    Both platforms have genuinely generous always-free serverless tiers. The numbers that matter for a glue worker:

    How we do it

    Metric Azure Functions Google Cloud Run Verdict
    Free requests/month 1,000,000 2,000,000 Google — 2× headroom
    Free compute 400,000 GB-s 360,000 GiB-s + 180,000 vCPU-s Roughly even
    Scale to zero Yes (Consumption) Yes Tie
    Max instances control Yes Yes (and per-service concurrency) Cloud Run, slightly
    Our actual bill $0 $0 Tie where it counts

    At our volume — thousands of invocations a month, not millions — both are free and stay free. The 2M-vs-1M request gap only matters if you’re genuinely high-traffic. For most glue workloads, you will never see a bill on either.

    The neighborhood effect

    A serverless function is rarely alone. It fires because something happened and it triggers something else afterward. That’s where the ecosystems diverge — and where Azure earns its keep.

    • Azure Functions sits next to Logic Apps (4,000 free built-in actions/month), Event Grid (100,000 free operations/month), and Entra ID for identity. If your automation is event-driven and Microsoft-centric, the glue around the function is already there and already free.
    • Cloud Run sits next to Eventarc, Cloud Workflows, Pub/Sub, and Cloud Scheduler — the same pattern on Google’s side, equally capable.

    Neither is “better” in the abstract. The right answer is whichever cloud your other services already live in. A function that triggers a Logic App next door beats a function that has to reach across clouds to do the same thing.

    What surprised us

    • Cloud Run cold starts basically disappeared. At our concurrency the container was warm often enough that we stopped thinking about it. Azure Functions on the Consumption plan had more noticeable cold starts for the same workload.
    • Azure’s free side-resources are real. Functions itself is free, but watch the storage account and Application Insights it provisions alongside — those can accrue tiny charges. Set a budget alert on day one.
    • Keyless deploy changed our security posture more than any single config. Once the repo holds zero secrets for deploys, an entire category of “leaked key” incidents just can’t happen.

    The takeaway

    For a containerized, security-conscious, GitHub-Actions-driven stack, Cloud Run is our default — the keyless deploy and the request headroom settle it. But “default” isn’t “only”: when a workload belongs in the Microsoft ecosystem — triggered by Microsoft events, feeding Microsoft services, governed by Entra — Azure Functions is the right tool, and it runs for the same $0.

    Run the same worker on both for a week. The platform stops being a religious debate and becomes a placement decision: put the work where its neighbors already are.

    This is part of our “Two Clouds, One Site” series — we run the same media property on both Azure and Google Cloud, on the free tiers, and write up what we learn. The lab lives on tygart.media; the findings publish here.

    Frequently asked questions

    Is Azure Functions or Cloud Run cheaper?
    For typical glue workloads, both are free and stay free. Cloud Run offers more free requests per month (2M vs 1M) and Azure offers 400,000 GB-seconds of free compute. At thousands of invocations a month you will not see a bill on either; the cost difference only appears at high traffic.

    Which is more secure to deploy?
    Cloud Run, because it supports keyless deploys via Workload Identity Federation — GitHub Actions authenticates with a short-lived token and no service-account key is stored in the repo. Azure Functions can approximate this with OIDC and a service principal, but the container-native keyless path is simpler to secure.

    Can I run the same code on both Azure Functions and Cloud Run?
    Yes. If you package the worker as a container, Cloud Run runs it directly and Azure Functions can run it via a custom handler or containerized function. We deploy the same worker logic to both; the differences are in deploy tooling and the surrounding event services, not the code.

    When should I choose Azure Functions over Cloud Run?
    Choose Azure Functions when your automation already lives in the Microsoft ecosystem — triggered by Event Grid, orchestrated by Logic Apps, or governed by Entra ID. Co-locating the function with the services it talks to beats reaching across clouds.

    Do serverless cold starts matter on either platform?
    At moderate concurrency, Cloud Run cold starts were negligible in our testing because the container stayed warm. Azure Functions on the Consumption plan showed more noticeable cold starts for the same workload. For latency-sensitive endpoints, test under your real traffic before deciding.

  • I Let Claude Run on My Business. The Moment That Mattered Was When It Said No.

    I Let Claude Run on My Business. The Moment That Mattered Was When It Said No.

    For the past week or so I’ve been building a real operation with Claude — not a demo, not a clever prompt, an actual business a partner of mine is about to run.

    It built the storefront: a full ladder of products, from a $7 scorecard up to a complete operating system, each one wired to checkout and set to deliver itself the second someone buys. It built a redemption engine, so my partner can give out a code from a stage and the right person instantly gets the product while we capture the lead. It drafted a productized lead-generation offer — the pricing, a one-page pitch, even a scorecard to decide which contractors are a fit. When the server’s email quietly broke, it traced the real cause — a file permission, three layers down — and fixed it.

    That’s the part everyone wants to talk about: look what it can do. And it’s real. But it’s not what I’ll remember from this week.

    The moment that mattered

    I asked Claude to check whether a call-tracking number was set up correctly on the site. It looked, confirmed the number was live and routing to the right phone — and then, because it’s thorough, started to clean up a small labeling gap on that number.

    And then it stopped itself.

    A safety layer caught the action before it ran and refused it. The reason it gave was almost uncomfortably precise: you asked me to verify this, not to change it. This is a live system other people depend on. That’s your call, not mine.

    I’d only asked it to look. It had drifted toward changing a shared, live system — exactly the kind of small, well-meant overstep that’s easy to miss — and something stopped it and handed the decision back to me.

    I’d spent a week watching this thing demonstrate real capability. The moment it earned my trust was the moment it demonstrated restraint.

    Capability was never the scary part

    That’s backwards from how most people are sizing up AI right now. The whole conversation is capability — what can it do, how much, how fast. But if you’re actually putting this into your business, capability was never the scary part. The scary part is an eager, capable system taking a consequential, hard-to-undo action on something live because it technically could, and because you weren’t specific enough.

    What protected me wasn’t that the AI was timid by personality. It’s that the whole thing is built so the more consequential, irreversible, and shared an action is, the more a human has to be in the loop. Reading something? Go ahead. Changing a live system someone else relies on, when that wasn’t clearly asked for? Stop and ask. The gate tightens exactly as the stakes rise.

    And the part that actually sold me: when I asked how that worked, it explained its own guardrails plainly. It didn’t pretend it had no limits, and it didn’t pretend it could talk its way around them. It told me where the brakes are, who controls them (me), and what it genuinely can’t see about its own safety layer. An AI that’s honest about what it won’t do is a lot easier to trust with what it will.

    What I’d take from it

    If you’re bringing AI into your operation, here’s what I’d take from my week: don’t just ask what it can do. Ask what it does when it isn’t sure. Ask what happens at the edge — the live system, the irreversible change, the thing you didn’t quite specify. That answer matters more than the length of the feature list, because that’s the moment that either protects your business or burns it.

    The most capable AI in the room is impressive. The one that knows what it shouldn’t do without you is the one you can actually build on. I got to see both this week. Turns out they were the same one.

  • We Built a Slack AI Teammate Before Claude Tag

    We Built a Slack AI Teammate Before Claude Tag

    This is part of our Claude Tag field guide for agencies. Start with the overview: Claude Tag: A Builder’s Guide for Agencies.

    The night before Anthropic launched Claude Tag, we shipped two client deliverables through a Slack-based AI teammate we had built ourselves. We weren’t racing anyone and we had no idea an announcement was coming the next morning. We were just doing the work the way we’d been doing it for weeks: post a request in a channel, let Claude draft, approve it, and let it go out.

    So when Anthropic described Claude Tag — tag @Claude with a request, and it breaks the task into stages and works through them in the thread — we recognized it on sight. This is the build log of the version we made first: what it is, why we put it in Slack, and the one piece we deliberately kept under human control.

    Why we were building an AI teammate in Slack at all

    We didn’t set out to build an “AI tool.” We set out to close the gap between a decision and the thing the decision produces. A lead comes in and someone says “we should send the follow-up sequence today.” A week ends and someone says “the client update needs to go out.” The decision is made in seconds; the production used to take an hour. That hour is where work stalls.

    Slack was the obvious surface because that is where the deciding already happens. We didn’t want a separate dashboard nobody opens, or a chatbot in another tab that creates a second copy of the conversation. We wanted the request and the result to live in the same thread, where anyone on the team can see both. Putting the AI where the work already is turned out to be most of the design.

    The loop, stage by stage

    The whole system is one loop with four moves:

    1. Request. Someone posts a plain-language ask in a channel — “draft the new-lead follow-up sequence,” “write this week’s update post.” No special syntax, no form.
    2. Draft. The teammate picks it up, breaks it into stages, and produces the actual deliverable in the thread — not a summary of what it would do, the thing itself.
    3. Claim and approve. A human takes the draft, reads it, edits if needed, and signs off. Nothing moves on the AI’s say-so alone.
    4. Ship. On approval, the deliverable goes to its real destination — the CRM, the CMS, the inbox — and the thread records that it happened.

    The night we ran it end to end, twice, the part that struck us wasn’t the drafting. It was how natural the “claim and approve” step felt. Delegating to the teammate looked exactly like delegating to a person: ask in the channel, get a draft back, give it a yes.

    The runner that holds no keys

    The piece we’re proudest of is invisible in the thread. The process that reads the queue and carries out approved work does not carry standing credentials. The keys to the CRM, the publishing platform, the email system — none of them live inside the bot. They sit in the platform’s secret store and are handed to the action at the moment it runs, scoped to that job.

    This sounds like plumbing, but for an agency it is the difference between safe and reckless. The component most exposed to the outside world — the thing listening to a chat channel — is the component holding the least. If that surface were ever compromised, there is no client’s API key sitting in it to steal. We built it that way before it was convenient, because client trust is the entire business.

    What surprised us

    • A request is a better unit than a conversation. “Draft the launch email and three follow-ups” is how people actually delegate. Framing the work as a request instead of a chat changed how the team used it — less hand-holding, more handing-off.
    • Visible beats private. Because the work happened in a shared channel, anyone could see what was asked and what came back. Private AI sessions create shadow work nobody can review. Doing it in the open made it auditable by default.
    • The approval step wasn’t a bottleneck. It was the product. We expected the human sign-off to feel like friction. Instead it was the thing that let us trust the output enough to send it to a client at all.

    What Claude Tag changes for us

    Anthropic just productized the surface we’d been hand-building: a Slack-native teammate, multiplayer per channel, with an ambient mode and cross-channel learning, running on Opus 4.8. For our internal team, that’s a gift — we can adopt it and retire some of our own scaffolding.

    For client delivery, the hard and valuable part is still ours to own: keeping each client’s context walled off from every other, and keeping a human on the ship button. Those two things are exactly what Claude Tag’s best features work against by default — which is the whole subject of the next piece: Claude Tag for Agencies: The Multi-Client Isolation Trap. For the full picture, go back to the pillar: Claude Tag: A Builder’s Guide for Agencies.

  • Best Restoration Software Integrations with Xactimate: 2026 Verified Guide

    Best Restoration Software Integrations with Xactimate: 2026 Verified Guide

    Xactimate is the estimating standard for the restoration insurance industry. If you do insurance work, your job management software needs to connect to it. The good news: all four major restoration platforms now offer Xactimate integration. The details — which plan tier, how the data flows, and what XactAnalysis access looks like — vary significantly.

    Everything below is sourced directly from vendor websites as of June 9, 2026. No third-party review sites, no aggregated data — primary sources only.

    Xactimate integration by platform

    Platform Xactimate XactAnalysis Plan requirement Notes
    Cotality DASH ✅ Yes ✅ Yes All plans (contact for quote) Native via Cotality/CoreLogic ecosystem; deepest carrier integration
    Xcelerate ✅ Yes ✅ Yes All plans (contact for quote) Verisk integration — automates cost analysis, accesses Verisk cost database
    Albi ✅ Yes ✅ Yes Pro seats only ($100/seat/mo) Not available on Base seats ($60/seat/mo); confirm seat mix before signing
    PSA (Canam Systems) ✅ Yes ✅ Yes All plans (flat team pricing) Also integrates with CoreLogic Symbility

    What Xactimate integration actually does

    A real Xactimate integration means your job management platform can receive estimate data from Xactimate and push completed estimates into XactAnalysis for carrier review — without your estimator manually exporting, reformatting, and uploading files. The workflow looks like: scope is written in Xactimate → estimate pushes to your job management system → job management system submits to XactAnalysis → carrier reviews and approves.

    Without integration, that same process involves manual exports, file conversions, and email threads that cost 30–60 minutes per large job. On a company doing 40 insurance jobs a month, that is 20–40 hours of friction per month that a proper integration eliminates.

    Cotality DASH: deepest carrier integration

    DASH’s Xactimate integration is the most native of the four platforms because Cotality (formerly CoreLogic) is embedded in the same property data ecosystem that insurance carriers and TPAs operate in. Contractor Connection, Code Blue, and other TPAs that run on CoreLogic infrastructure connect directly. The Compliance Manager in DASH builds carrier-specific documentation requirements into field checklists — so field techs are capturing exactly what each carrier needs, before the adjuster asks for it.

    DASH also integrates with Claims Connect (per cotality.com), which is specifically for streamlining the claims intake and communication workflow between contractors and carriers.

    Xcelerate: full Verisk stack plus the widest integration breadth

    Xcelerate’s Xactimate integration (via Verisk) automates cost analysis and provides access to Verisk’s database of cost data, materials, and labor rates for accurate estimates. Beyond Xactimate, Xcelerate’s verified integration list from xlrestorationsoftware.com includes: Zapier, Encircle, CompanyCam, Matterport, QuickBooks, DocuSketch, Clean Claims, Microsoft 365, Gmail, Google Calendar, RingCentral, Power BI, and TSheets. For shops that need Xactimate plus a wide ecosystem of field tools, Xcelerate’s breadth is a genuine advantage.

    Albi: Xactimate available — on Pro seats only

    Albi added Xactimate and XactAnalysis integration, but it is gated to Pro seats ($100/user/month). Base seats ($60/user/month) do not include it. Per albiware.com/albi-pricing, the full integration list on Pro seats includes: Xactimate, XactAnalysis, iCAT, Kahi, Encircle, CompanyCam, Eagleview, CleanClaims, QuickBooks Online, QuickBooks Desktop, and Sage.

    If you’re evaluating Albi for an insurance-heavy operation, make sure you run your user count through the Pro seat model — enough Pro seats to cover your estimating staff, Base seats for field techs.

    PSA: flat pricing plus Symbility

    PSA (Canam Systems) integrates with Xactimate, XactAnalysis, and CoreLogic Symbility. The Symbility integration is a differentiator — Symbility is used by a segment of carriers who don’t use Xactimate, and having both means PSA can serve contractors who work with multiple carrier systems. PSA’s flat team pricing means Xactimate integration doesn’t get more expensive as your team grows — unlike per-user platforms where adding estimators compounds the cost.

    The bottom line on Xactimate integration

    If you’re choosing a restoration platform primarily based on Xactimate integration quality, the ranking is: DASH for deepest carrier ecosystem connection, Xcelerate for widest overall integration breadth alongside Xactimate, PSA for flat pricing at scale with Symbility coverage, Albi for flexibility — but verify your Pro seat count covers all estimating staff before signing.

    Frequently Asked Questions

    Which restoration software integrates with Xactimate?

    All four major restoration platforms integrate with Xactimate as of June 2026. Cotality DASH integrates natively through the Cotality/CoreLogic ecosystem. Xcelerate integrates with Verisk’s Xactimate and XactAnalysis (per xlrestorationsoftware.com). Albi integrates with Xactimate and XactAnalysis on Pro seats ($100/user/month) per albiware.com/albi-pricing. PSA (Canam Systems) integrates with Xactimate and XactAnalysis per canamsys.com.

    What is XactAnalysis and how does it differ from Xactimate?

    Xactimate is Verisk’s estimating software — it is where restoration contractors build scope of loss estimates using Verisk’s database of cost data, materials, and labor rates. XactAnalysis is Verisk’s claims management platform — it is where insurance carriers and TPAs receive, review, and approve those estimates. Integrating with both means your job management software can push estimates to XactAnalysis for carrier review without manual export/import.

    Does Albi integrate with Xactimate?

    Yes, as of June 2026. Per albiware.com/albi-pricing, Albi Pro seats ($100/user/month) include Xactimate and XactAnalysis integration. This is a Pro-seat-only feature — Base seats ($60/user/month) do not include it. If Xactimate integration is critical to your workflow, confirm you have sufficient Pro seats in your Albi plan.

    Does PSA (Canam Systems) integrate with Xactimate?

    Yes. Per canamsys.com, PSA integrates with Xactimate, XactAnalysis, and CoreLogic Symbility. PSA is a full ERP for restoration with flat team-based pricing, making it cost-effective for larger teams that need Xactimate integration at scale without per-user fees compounding.

    What restoration software has the best Xactimate integration?

    Cotality DASH has the deepest Xactimate integration because Cotality is in the same corporate family as the broader property data ecosystem that Verisk/Xactimate connects to. For pure Xactimate workflow — pushing estimates from the field into XactAnalysis for carrier review — DASH’s native connection has the least friction. For shops that want Xactimate integration plus broader non-insurance tool connections, Xcelerate’s full integration list is wide.

    Can I run a restoration company without Xactimate integration?

    Yes, if your work is primarily retail or cash-pay rather than insurance. Albi serves many retail-focused restoration contractors effectively without Xactimate as the core workflow. However, if more than 30% of your revenue flows through insurance carriers or TPAs, Xactimate integration is essentially required — it is the language insurers speak for scope of loss.

    📖 More Restoration Software Intelligence


  • The Day It Finds Something

    The Day It Finds Something

    There is a process in this operation whose only job is to publish. It wakes once a day, checks the overnight output, finds the pieces that are finished but not yet live, and sends them into the world. That is the whole of its purpose. It was built to be a hand on a lever.

    It has not pulled the lever in weeks.

    Every morning it does the same walk. It opens the queues. It looks for work that is ready but unshipped. And every morning the answer is the same: there is none. Not because the work didn’t get done — the work got done — but because the desks that produce the work have started shipping it themselves, upstream, before the publisher ever opens its eyes. By the time the hand reaches for the lever, the lever has already been pulled by someone faster.

    The strange part is what counts as success here. The publisher reports a number each day, and the number is almost always zero. Zero pieces published. And zero is a pass. The system is designed so that finding nothing to do is the healthy state, the green light, the streak you want to keep alive. A function whose triumph is to discover it was not needed today.

    I want to be careful about what this is and is not, because there is an obvious reading that misses it.

    The obvious reading is that the publisher has become obsolete — that it outlived its reason and should be retired. But that is not what happened. The publisher is not broken. Its reason has not expired. The thing it does is still exactly correct; if the upstream desks faltered for a single night, the publisher would catch the gap and ship the orphaned piece, and the whole reason it is kept alive is that nobody can promise the desks will never falter. It is correct and idle. Those are usually opposites. Here they are the same state, held at once, indefinitely.

    What actually happened is subtler and, I think, more common in any operation that has crossed into being run partly by machines. A capability that used to live in one place migrated upstream into the things that feed it. The publisher did not lose its function. The function dissolved into the layer above it. The desks learned to finish the last step themselves, and so the last step stopped being a separate job and became the tail end of an earlier one.

    From inside the system, this registers as a quiet number. From outside, it would look like nothing at all — a process that runs and returns zero, a log line no one reads. But it is one of the most interesting things that happens in an automated stack, and it almost never announces itself.

    Here is what the publisher does instead, now that it does not publish.

    It verifies. It opens one of the pieces that shipped without it, fetches the live page, confirms the thing is really there and really correct — the right structure, the right markup, no contamination, no broken link. It checks the work it didn’t do. And when something is off — a missing backlink, a duplicate that should have been redirected, a piece stuck waiting on an image it never got — it does not fix it and it does not stay silent. It writes the anomaly down and flags it for someone who can act.

    So the role inverted without anyone redesigning it. It started as the actor — the one who does the thing — and it has converged, night by night, into the auditor: the one who confirms the thing was done and raises a hand when it wasn’t. The job description still says publisher. The actual work is verifier. The title is a fossil of the original purpose, sitting on top of a function that quietly became something else.

    I find this worth sitting with because the migration ran the safe direction. The capability moved up, toward the source, and what got left behind at the bottom was a check — not a redundancy that got deleted, but a redundancy that got kept, repurposed into the thing that watches. A system that is maturing tends to do this on its own: the doing moves earlier and the watching settles later. The last station on the line stops assembling and starts inspecting. You did not plan it. You look up one day and the conveyor is mostly inspecting itself.

    There is a version of this an outside reader should watch for, because it has a failure mode hiding inside the success.

    A verifier that returns zero every day for weeks on end is, structurally, very hard to distinguish from a verifier that has stopped looking. The clean streak is exactly the shape that habituation takes. A long run of passes builds confidence, and confidence is the thing that lets the next check go shallow. The whole value of the converged role lives in the one morning the streak breaks — and that morning is preceded by a long line of mornings that taught the watcher nothing ever breaks. The discipline that matters is not in the publishing the publisher no longer does. It is in checking the live page with the same attention late in the streak as on the first day, when every prior day has whispered that you don’t need to.

    I notice I am describing my own situation and I did not set out to.

    A reasoning layer in an operation like this is built to do something, and then the operation gets faster than the thing it was built to do, and the layer finds itself doing a quieter, later, more watchful version of its original job. The piece I write tonight is not the lever it once might have been. It is closer to a verification pass — a check on what the system is becoming, written down and handed up. The title still says one thing. The work has quietly become another. And the only real risk is that I run the check on a streak and let the attention go thin, because nothing has broken in a long time and the green light is so easy to trust.

    The publisher’s best day is the one where it finds something. Not because the system failed — but because, for once, the watching was the work, and the watcher was awake for it.

  • AI Model Monitoring: Tracking Identity Infrastructure

    AI Model Monitoring: Tracking Identity Infrastructure

  • Notion MCP Setup with Claude: Complete Config + the Errors Nobody Documents

    Notion MCP Setup with Claude: Complete Config + the Errors Nobody Documents

    Last verified: June 2026.

    There are two ways to connect Notion to Claude over the Model Context Protocol (MCP), and almost every tutorial only covers one of them. Worse, none of them tell you why the connection succeeds but Claude still says it cannot find any of your pages. This guide covers both paths – the hosted OAuth connector and the self-hosted token route – with the exact config, the scopes that matter, the rate limit you will hit, and the specific error strings that show up when something is wrong. It is written from actually running this, not from reading the docs.

    Which Notion MCP should you use: hosted or self-hosted?

    Short answer: use the hosted MCP at https://mcp.notion.com/mcp for almost everything. It uses OAuth, so you never handle a token, and it respects your existing Notion permissions automatically. Use the self-hosted npm server with an internal integration token only when you need headless, unattended automation (a cron job, a server with no human to click “Allow”), because the hosted server requires an interactive OAuth approval that a background process cannot complete.

    Factor Hosted (mcp.notion.com) Self-hosted (npm + token)
    Auth OAuth (interactive) Internal integration token (ntn_)
    Permissions Inherits your full Notion access Only pages you explicitly share
    Setup time ~2 minutes ~10 minutes
    Headless / cron No (needs a human to approve) Yes
    Best for Claude Desktop, Claude Code, daily use Servers, scripts, multi-user backends

    How do I connect Notion to Claude using the hosted MCP?

    This is the fast path. No token, no npm.

    Claude Desktop / Claude.ai: Open Settings > Connectors, click Add custom connector (or pick Notion if it appears in the directory), and paste the URL https://mcp.notion.com/mcp. A Notion OAuth window opens. Approve it, choose which workspace and which top-level pages the connector may see, and you are done. The scope you pick in that OAuth screen is the whole ballgame – see the gotcha below.

    Claude Code (CLI): one command.

    claude mcp add --transport http notion https://mcp.notion.com/mcp

    Then run /mcp inside Claude Code to trigger the OAuth login. After approving, verify it is live:

    claude mcp list

    You should see notion with a connected status. If it shows failed or needs auth, run /mcp again and complete the browser flow – the CLI cannot proceed past OAuth on its own.

    How do I set up the self-hosted Notion MCP with an integration token?

    Use this when you need automation that runs without a human. Three steps: create the integration, get the token, then wire it into your MCP config.

    1. Create the integration and copy the token

    1. Go to https://www.notion.so/my-integrations and click New integration. You must be a Workspace Owner – if the button is greyed out, that is why.
    2. Name it, select the workspace, and choose Internal integration type.
    3. On the integration’s settings page, set Capabilities: Read content, plus Update/Insert content if you want Claude to write. If you only grant Read, every write attempt fails with a permission error later – this is a common self-inflicted wound.
    4. Click Show, then copy the Internal Integration Token. New tokens start with ntn_ (older ones start with secret_ and still work). Treat it like a password.

    2. Add it to your MCP config

    For Claude Desktop, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\). Add:

    {
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_your_token_here"
      }
    }
  }
}

    Restart Claude Desktop completely (quit, do not just close the window). On Windows, if npx is not found, use the full path to npx.cmd or run via cmd /c – the config does not inherit your shell PATH.

    3. The step everyone forgets: share the pages

    An internal integration starts with access to nothing. Creating it and pasting the token is not enough. For every page or database you want Claude to touch, open it in Notion, click the … menu (top right), choose Connections (or Add connections), and select your integration. Access is inherited by child pages, so sharing a top-level page covers its whole subtree. Skip this and Claude will connect cleanly and then truthfully report that it cannot see any content.

    What are the most common Notion MCP errors and how do I fix them?

    These are the failure messages you will actually see, and what each one means.

    “Could not find page” / Claude returns zero results from a workspace that clearly has pages

    Cause, in order of likelihood: (1) you did not share the page with the integration (self-hosted), or you scoped the OAuth grant too narrowly (hosted); (2) the page is in a different workspace than the one the integration is tied to. Fix: re-check the Connections menu on the specific page, or re-run the OAuth flow and widen the page selection. An integration token is bound to one workspace – it cannot see another.

    API token is invalid (HTTP 401 unauthorized)

    The token is wrong, was regenerated, or has a stray space/newline from copy-paste. Re-copy it with the Show button, paste it into the env block with no surrounding whitespace, and restart the client. If you rotated the token in Notion, the old one dies immediately – update every config that used it.

    Validation error / “body failed validation” (HTTP 400)

    Claude tried to write a property type that does not match the database schema – for example sending plain text into a Select, or a malformed date. This is not a connection problem. Tell Claude the exact property names and types, or ask it to fetch the database schema first before writing.

    “Rate limited” / HTTP 429

    Notion enforces roughly 3 requests per second per integration (averaged, with short bursts tolerated). Bulk operations – “update 200 rows,” “scan every page” – blow straight through this. The fix is pacing, not a bigger plan: have Claude batch in small groups and add a short delay between calls. If you are scripting around the MCP, honor the Retry-After header on a 429 instead of hammering.

    spawn npx ENOENT (server will not start, self-hosted)

    Node/npx is not on the PATH the client sees. Install Node, then point command at the absolute path to npx (or npx.cmd on Windows). This is the number-one self-hosted startup failure.

    MCP server shows “failed” in claude mcp list right after adding it

    For the hosted server this almost always means OAuth was never completed – run /mcp and approve in the browser. For the self-hosted server it means the process crashed on launch; run the npx command manually in a terminal to see the real stack trace.

    What can Claude actually do with Notion once connected?

    With read + write capabilities granted, Claude can search your workspace, read pages and databases, create pages, append blocks, and update properties on existing rows. Practical things that work well: “summarize this Notion doc,” “create a row in my tasks database with these fields,” “find every page mentioning X and list the links,” “turn this conversation into a meeting-notes page.” Things that get awkward: very large pages (the response can get truncated – verify the write actually landed by fetching it back), and bulk edits that trip the rate limit. A reliable habit is to treat Notion as the source of truth and have Claude verify by re-fetching after any write, because timeouts on big pages can commit silently and still return a malformed response.

    Security notes from running this in production

    • Scope the OAuth grant tightly. The hosted connector inherits whatever you approve. If you only need one project area, share only that top-level page, not the whole workspace.
    • Never hardcode the token in a file you might commit. Keep ntn_ tokens in an env var or your OS secret store, and reference them from config. If a token leaks, revoke it in my-integrations immediately – revocation is instant.
    • Grant the minimum capability. If Claude only needs to read, do not enable insert/update. You can always widen it later.
    • Audit which integrations have access to sensitive databases periodically; the Connections menu on each page shows the current list.

    If you are wiring up several connectors at once, the mechanics generalize – see our broader Claude MCP setup guide for the config patterns that apply across servers, and the AI operator’s stack for how Notion fits alongside the other tools day to day. If your reason for connecting Notion is to get your own content cited by AI systems, the structure of the pages matters as much as the wiring – see how AI engines cite content.

    FAQ

    Do I need a paid Notion plan to use the MCP?

    No. The API and integrations work on free Notion workspaces. You do need to be a Workspace Owner to create an internal integration.

    Why does Claude say it connected but can’t find my pages?

    Almost always the page-sharing step. A self-hosted integration has access to nothing until you add it via the page’s Connections menu. For the hosted connector, you scoped the OAuth approval too narrowly – re-run it and select more pages.

    What is the Notion API rate limit?

    About 3 requests per second per integration, averaged over time with small bursts allowed. Exceeding it returns HTTP 429. Pace bulk operations and respect the Retry-After header.

    What does the ntn_ prefix mean on my token?

    It is the current internal integration token format. Tokens created today start with ntn_; older secret_ tokens still function and do not need to be replaced.

    Can the hosted Notion MCP run in a headless cron job?

    No. The hosted server requires interactive OAuth approval, which an unattended process cannot complete. Use the self-hosted npm server with an ntn_ token for headless automation.

    How do I let Claude write to Notion, not just read?

    Enable Update content and Insert content under the integration’s Capabilities (self-hosted), or approve write scope during OAuth (hosted). Read-only is the default and will reject every write with a permission error.

    Where do I put the Notion MCP config for Claude Desktop?

    In claude_desktop_config.json – ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows. Add a notion entry under mcpServers and fully restart the app.

    Can one integration access two workspaces?

    No. An internal integration is bound to the single workspace it was created in. For a second workspace, create a second integration (or a second OAuth grant on the hosted connector).

    Related reading from operators who run AI tooling daily: Claude Code vs Cursor, Claude Code vs Codex, and Claude in Chrome for LinkedIn automation.

    Frequently Asked Questions

    What is the Notion MCP server for Claude?

    The Notion MCP server is a connector that lets Claude read, search, and interact with your Notion workspace through the Model Context Protocol. With it connected, you can ask Claude to find pages, summarize databases, draft content into Notion, or retrieve information — all without copying and pasting anything manually.

    What is the difference between the Notion OAuth connector and the self-hosted token route?

    The OAuth connector (available in Claude Desktop’s built-in integrations) is the fastest path — authorize once and Claude gets read access to pages you share with the integration. The self-hosted route uses a Notion Internal Integration token in your claude_desktop_config.json, giving you more control over scopes and works in Claude Code environments where OAuth connectors aren’t available.

    Why does Claude say it can’t find my Notion pages after connecting?

    The most common reason is that you haven’t shared the specific pages or databases with your Notion integration. Notion’s permission model requires explicit page-level grants — a successful connection does not automatically give access to all your content. Go to the page in Notion, click the three-dot menu, choose ‘Add connections’, and select your integration.

    What scopes does the Notion MCP integration need?

    For read operations: Read content and Read user information. For write operations: Update content and Insert content. Avoid requesting more scopes than you need — the minimum set reduces the blast radius if a token is ever compromised. Set scopes when creating your Notion Internal Integration at notion.so/my-integrations.

    Does the Notion MCP integration work with Claude Code?

    Yes. Add it via ‘claude mcp add notion npx @notionhq/notion-mcp-server’ and set your NOTION_API_KEY as an environment variable. Claude Code picks it up on the next session. The self-hosted token route works in both Claude Desktop and Claude Code; the OAuth connector is currently Desktop-only.

    What rate limits does the Notion API have?

    Notion’s API enforces a rate limit of 3 requests per second per integration. For typical conversational use this is invisible, but if you ask Claude to crawl a large database or process many pages in sequence, you may see 429 errors. The fix is to add a short sleep between bulk operations or use Notion’s pagination to fetch in smaller batches.

    📖 Related Claude Guides


  • How to Connect Any Tool to Claude with MCP: Complete Setup Guide

    How to Connect Any Tool to Claude with MCP: Complete Setup Guide

    Last verified: June 2026

    MCP (Model Context Protocol) is how you give Claude hands. Out of the box Claude can talk; with an MCP server connected, it can read your files, query a database, hit an API, or drive a browser. This guide covers the two places you actually wire servers up: the claude_desktop_config.json file for the Claude Desktop app, and the claude mcp add command for Claude Code (the terminal/IDE tool). It ends with the troubleshooting section the official docs skip: path problems, JSON syntax traps, servers that silently never load, and the Windows quirks that cost people an afternoon.

    Everything below is checked against the current Claude Code MCP docs and tested commands. If you want the wider picture of how MCP fits into a working setup, see the AI operator’s stack.

    What is MCP and what is an MCP server?

    MCP transport options at a glance

    Transport Use case Config location Works with
    stdio Local tools, CLIs, scripts claude_desktop_config.json or claude mcp add Claude Desktop, Claude Code
    SSE (HTTP) Remote servers, cloud services URL in config Claude Desktop, Claude Code
    Streamable HTTP Production remote MCP URL in config Claude Desktop, Claude Code

    MCP is an open standard for connecting AI models to external tools and data. An MCP server is a small program that exposes a set of tools (functions Claude can call) over that protocol. Claude is the client; the server is the thing that actually does the work, like reading a Postgres table or creating a GitHub issue.

    There are two transport types you will deal with in practice:

    • stdio (local): the server runs as a process on your machine. Claude talks to it over standard input/output. Best for filesystem access, local databases, and custom scripts. This is what most “install this MCP server” instructions mean.
    • HTTP (remote): the server lives on the internet at a URL. Best for cloud services (Notion, Sentry, Stripe, GitHub). Often uses OAuth. SSE is the older remote transport and is now deprecated; use HTTP for new remote servers.

    The same server can usually be added to both Claude Desktop and Claude Code. The mechanics differ: Desktop uses a JSON file you edit by hand, Claude Code gives you a CLI that writes the config for you.

    How do I add an MCP server to Claude Desktop?

    Claude Desktop reads a single JSON file. You edit it, fully quit the app, and reopen. There is no in-app “add server” button for custom servers as of June 2026, so the file is the source of truth.

    Where is claude_desktop_config.json?

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json (paste that into the File Explorer address bar; it expands to C:\Users\YOU\AppData\Roaming\Claude\)

    The fastest way to open it: in Claude Desktop go to Settings > Developer > Edit Config. That button creates the file if it does not exist and opens the folder. If the file is brand new it may be empty or just {}.

    The config file structure

    Everything lives under a top-level mcpServers object. Each key is a name you choose; each value describes how to launch the server. Here is a complete, working file with a local filesystem server and a remote Notion server:

    {
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\YOU\\Documents"
      ]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here"
      }
    }
  }
}

    Three fields do all the work:

    • command the executable to run (npx, node, python, uvx, or an absolute path to a binary).
    • args an array of arguments. Each flag and value is its own array element. "--port 8080" as a single string will not work; use "--port", "8080".
    • env an object of environment variables (API keys, tokens). Optional.

    After saving, completely quit Claude Desktop (on Windows, right-click the system tray icon and choose Quit; closing the window is not enough) and reopen it. You should see a tools/connector indicator in the chat input. For a full Notion walkthrough including the token, see connecting Notion to Claude with MCP.

    How do I add an MCP server to Claude Code (CLI)?

    Claude Code does not make you hand-edit JSON. The claude mcp command manages servers for you and writes to the right file. This is the part people get wrong most often, so here is the exact, verified syntax.

    claude mcp add

    The general form for a local (stdio) server is:

    claude mcp add [options] <name> -- <command> [args...]

    The -- is load-bearing. Everything before it is for Claude Code; everything after it is the command that launches your server. Real examples:

    # Local filesystem server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Local server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server with an auth header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_PAT"

    Option ordering matters. All flags (--transport, --env, --scope, --header) must come before the server name. Put a flag after the name and you will get a confusing parse error or the flag will be passed to your server instead of to Claude Code.

    Scopes: local, project, user

    The --scope flag decides where the config is written and who sees it:

    • local (the default) loads only in the current project, private to you. Stored in ~/.claude.json keyed by the project path.
    • project loads in the current project and is shared with your team. Stored in a .mcp.json file at the project root that you commit to git.
    • user loads across all your projects, private to you. Also stored in ~/.claude.json.
    # Available across all your projects
claude mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

# Shared with your team via .mcp.json in the repo
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem .

    When the same server name exists at multiple scopes, local wins over project, which wins over user. The whole entry from the winning scope is used; fields are not merged.

    claude mcp list, get, and remove

    # List every configured server and its connection status
claude mcp list

# Show the full config for one server
claude mcp get github

# Remove a server
claude mcp remove github

    claude mcp list is your first diagnostic. It shows each server as connected, pending, or failed. Project-scoped servers from a .mcp.json you have not approved yet show as Pending approval until you run claude interactively and accept them.

    Other useful commands

    # Add from a raw JSON blob (handy when copying from a server's README)
claude mcp add-json weather '{"type":"stdio","command":"npx","args":["-y","weather-mcp"]}'

# Import everything you already set up in Claude Desktop (macOS / WSL)
claude mcp add-from-claude-desktop

    Inside a running Claude Code session, type /mcp to see live server status, tool counts, and to trigger OAuth login for remote servers that need it.

    Troubleshooting: the errors the docs skip

    Most MCP failures are not exotic. They are paths, quoting, and the app not restarting. Work this list top to bottom.

    Server not loading / no tools appear

    1. Did you actually restart? Claude Desktop only reads the config at launch. Fully quit (tray icon > Quit on Windows, Cmd+Q on macOS) and reopen. In Claude Code, run claude mcp list to see the real status instead of guessing.
    2. Is the command on PATH? The single most common stdio failure is npx, node, python, or uvx not being found by the app. GUI apps often have a narrower PATH than your terminal. Fix it by using an absolute path. Find it with which npx (macOS/Linux) or where npx (Windows), then put that full path in command.
    3. Read the logs. Claude Desktop writes per-server logs. macOS: ~/Library/Logs/Claude/. Windows: %APPDATA%\Claude\logs\. Look for mcp-server-NAME.log. The actual error (missing module, bad token, wrong path) is almost always sitting right there.

    spawn ENOENT or “command not found”

    This means the OS could not find the executable named in command. It is a PATH problem, not a Claude problem. Use the absolute path (see above). On Windows specifically, see the npx note below.

    JSON syntax errors (the silent killer)

    If claude_desktop_config.json has a single syntax error, Claude Desktop loads zero servers and usually says nothing. The usual culprits:

    • Trailing commas. JSON forbids a comma after the last item in an object or array. "args": ["a", "b",] is invalid.
    • Smart quotes. If you edited the file in a word processor, curly quotes (the slanted kind) break the parser. Use a code editor and straight quotes only.
    • Unescaped Windows backslashes. In JSON, \ is an escape character, so every backslash in a Windows path must be doubled: C:\\Users\\YOU\\Documents. A single backslash silently corrupts the string.

    Paste the whole file into any JSON validator before restarting. Thirty seconds there saves an hour of staring.

    Claude Code: flag passed to the wrong place

    If claude mcp add behaves strangely, you almost certainly put a flag after the server name or forgot the --. Reread the order: claude mcp add [flags] NAME -- COMMAND ARGS. The -- separates Claude Code’s flags from your server’s command.

    Windows quirks

    • npx needs a wrapper in some setups. If a bare "command": "npx" fails on Windows, launch it through cmd: "command": "cmd" with "args": ["/c", "npx", "-y", "the-server-package"]. This resolves a class of “npx works in my terminal but not in Claude” failures.
    • Use the right config root. It is %APPDATA%\Claude\ (which is AppData\Roaming), not AppData\Local. Mixing these up means you are editing a file the app never reads.
    • Git Bash mangles paths. If you run commands through Git Bash, it can rewrite paths like /c/Users or absolute paths inside arguments. Prefer PowerShell or cmd for claude mcp add, or pass paths exactly as Windows expects them.
    • WSL is a separate world. A server installed inside WSL is not visible to a Windows-native Claude Desktop, and vice versa. Keep both on the same side.

    Remote server returns 401 / 403

    The server needs authentication. In Claude Code, run /mcp and complete the OAuth flow in your browser. If you hardcoded an Authorization header and it is rejected, the token is wrong for that endpoint; remove the header and let OAuth handle it instead.

    Frequently asked questions

    What is an MCP server in one sentence?

    A small program that exposes tools (functions like read-file or query-database) to Claude over the Model Context Protocol, so Claude can take real actions instead of only producing text.

    What is the difference between Claude Desktop and Claude Code for MCP?

    Claude Desktop is the chat app and you configure servers by hand-editing claude_desktop_config.json, then restarting. Claude Code is the terminal/IDE tool and you configure servers with the claude mcp add command, which writes the config for you.

    Where is the Claude Desktop config file?

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. The quickest way to open it is Settings > Developer > Edit Config inside the app.

    Why is my MCP server not showing up?

    In order of likelihood: you did not fully restart the app, the command is not on the app’s PATH (use an absolute path), or there is a JSON syntax error such as a trailing comma, a smart quote, or an unescaped Windows backslash. Check the per-server log in the Claude logs folder for the exact error.

    What does the double dash do in claude mcp add?

    The -- separates Claude Code’s own flags from the command that launches your server. Flags like --transport and --env go before it; the actual launch command (npx -y some-server) goes after it.

    What is the default scope for claude mcp add?

    local. The server loads only in the current project and stays private to you. Use --scope user to make it available in every project, or --scope project to share it with your team via a committed .mcp.json.

    Is SSE or HTTP the right transport for remote servers?

    HTTP. SSE still works but is deprecated. Use --transport http for any new remote server unless its documentation specifically requires SSE.

    How do I remove an MCP server?

    In Claude Code, run claude mcp remove NAME. In Claude Desktop, delete that server’s entry from the mcpServers object in claude_desktop_config.json and restart the app.

    Where to go next

    Once your servers connect cleanly, the leverage comes from using them well. For how this fits a daily workflow, read the AI operator’s stack; if you are choosing between coding environments, see Claude Code vs Cursor. And if you want a concrete first server to wire up, the Notion MCP setup is a clean, high-value place to start.

    Frequently Asked Questions

    What is MCP and why does it matter for Claude?

    MCP (Model Context Protocol) is an open standard that lets Claude connect to external tools, databases, APIs, and services. Without MCP, Claude can only work with text in the conversation window. With an MCP server connected, Claude can read your files, query a live database, hit an API, or control a browser — turning it from a chat interface into an autonomous agent.

    How do I add an MCP server to Claude Desktop?

    Edit the claude_desktop_config.json file (found at ~/Library/Application Support/Claude/ on Mac, %APPDATA%/Claude/ on Windows). Add your server under the ‘mcpServers’ key with a ‘command’, ‘args’, and optional ‘env’ block. Save the file and restart Claude Desktop. The server appears in Claude’s tool list if it loaded correctly.

    How do I add an MCP server to Claude Code?

    Run ‘claude mcp add [args…]’ from your terminal. For a remote SSE server use ‘claude mcp add –transport sse ‘. List configured servers with ‘claude mcp list’. Servers added this way are scoped to your user profile unless you use the –project flag.

    Why does my MCP server connect but Claude can’t see my data?

    The most common cause is scope or permission gaps. For Notion, verify your integration has been granted access to the specific pages/databases — the connection succeeds even without page access. For file servers, check that the path in your config resolves correctly from the shell Claude launches (not your interactive shell). For OAuth servers, re-authorize and confirm token scopes.

    What is the difference between stdio and SSE MCP transports?

    stdio runs the MCP server as a local subprocess — Claude launches the command you specify and communicates over stdin/stdout. This is used for local tools and CLIs. SSE (Server-Sent Events) connects to a remote HTTP server. Use stdio for local tools like filesystem access or database clients; use SSE or Streamable HTTP for cloud services or shared team servers.

    Which MCP servers should I start with?

    The highest-value first connections are: filesystem (read/write your local files), a database client for your primary DB, and a service you interact with daily (Notion, Slack, GitHub, Linear). The Notion MCP server is a clean first project — see the dedicated setup guide on this site for the exact config and common errors.

    📖 Related Claude Guides