{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreicvzz2zpilpw2vctlqptwlinrpqmonpjkn3ppg7bqq2pu543js7nq",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3mplofugqhdu2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreid2s6di26trxgo4z22s4ys3dsulo4ntxdoepgc3sbmqnkidqoe2wu"
    },
    "mimeType": "image/webp",
    "size": 58832
  },
  "path": "/michielinksee/stop-letting-claude-guess-your-saas-api-auth-flow-36p3",
  "publishedAt": "2026-07-01T13:37:29.000Z",
  "site": "https://dev.to",
  "tags": [
    "api",
    "claude",
    "llm",
    "saas",
    "@kansei-link"
  ],
  "textContent": "##  The problem\n\nClaude Code is great at writing integration code.\n\nBut when I ask it to connect to a SaaS API, the same annoying pattern keeps showing up:\n\n\n\n    Write auth code\n    ↓\n    Call the API\n    ↓\n    Auth error\n    ↓\n    Fix the scope\n    ↓\n    Missing required parameter\n    ↓\n    Fix again\n    ↓\n    Wrong endpoint version\n    ↓\n    Try again\n\n\nBy the time it works, I have burned thousands of tokens.\n\nThis happens a lot with SaaS APIs like Salesforce, HubSpot, Stripe, Slack, freee, SmartHR, kintone, and others.\n\nThe issue is not that Claude cannot write code.\n\nThe issue is that Claude often starts with stale assumptions.\n\nSaaS APIs change all the time:\n\n  * OAuth flows get updated\n  * PKCE becomes required\n  * API versions change\n  * required parameters get added\n  * rate limits change\n  * official docs get reorganized\n  * MCP servers behave differently from direct API calls\n\n\n\nIf the agent starts with the wrong connection assumptions, everything after that becomes a retry loop.\n\nSo I tried a simple fix:\n\n> Before letting Claude write API integration code, give it a connection guide.\n\n##  The idea\n\nInstead of asking Claude to connect directly to a SaaS API, I added an MCP server that tells Claude how to connect first.\n\n\n\n    claude mcp add kansei-link -- npx @kansei-link/mcp-server\n\n\nNo API key.\n\nNo auth.\n\nNo setup beyond that.\n\nNow the flow looks like this:\n\n\n\n    Before:\n    User → Claude → SaaS API\n                  ↑\n            guessing from stale knowledge\n\n    After:\n    User → Claude → KanseiLINK MCP → connection guide\n                  ↓\n               SaaS API\n\n\nThe goal is not to make Claude “smarter”.\n\nThe goal is to stop Claude from guessing.\n\n##  Example: Salesforce\n\nBefore writing code, Claude can ask KanseiLINK what it should know about the service.\n\n\n\n    search_services({ query: \"salesforce crm\" })\n\n\nExample response:\n\n\n\n    Salesforce\n    - Grade: BB\n    - Agent connection success rate: 43%\n    - Connection type: third-party MCP / API\n    - Auth: OAuth 2.0\n    - Known issues:\n      - complex scope configuration\n      - instance URL varies by org\n      - API version must be specified\n\n\nThen it can ask for the actual connection details.\n\n\n\n    lookup({ service_id: \"salesforce-crm\", detail: true })\n\n\nExample response:\n\n\n\n    Auth:\n      OAuth 2.0\n\n    Common pitfalls:\n      - instance URL varies per org\n      - API version must be specified\n      - third-party MCP servers may not support all write operations\n      - Bulk API has different requirements\n\n\nThat context is small, but it changes the output a lot.\n\nClaude starts from the right assumptions instead of writing a plausible but outdated integration.\n\n##  Example: freee accounting\n\nAnother example:\n\n\n\n    lookup({ service_id: \"freee-accounting\", detail: true })\n\n\nExample response:\n\n\n\n    Auth:\n      OAuth 2.0 + PKCE\n\n    Required:\n      company_id\n\n    Common pitfalls:\n      - PKCE is required\n      - company_id must be fetched before posting transactions\n      - endpoint versions are easy to confuse\n      - missing scopes cause auth failures\n\n\nThis is exactly the kind of information that prevents a 3-turn debugging loop.\n\n##  Before vs after\n\nI tested this on a few common SaaS integration tasks.\n\nThis is not a formal benchmark, but I tracked token usage and retries in my own Claude Code workflow.\n\nTask | Before | After | Reduction\n---|---|---|---\nSalesforce opportunity update | ~5,500 tokens | ~1,800 tokens | 67%\nHubSpot contact creation | ~3,400 tokens | ~1,200 tokens | 65%\nStripe invoice generation | ~2,800 tokens | ~1,100 tokens | 61%\nSlack webhook setup | ~2,100 tokens | ~900 tokens | 57%\n\nOn average, this reduced token usage by around **60–70%**.\n\nThe savings mostly came from removing failed retries.\n\nThe lookup itself is cheap.\n\nA failed retry is expensive.\n\n##  The MCP tools\n\nKanseiLINK MCP currently exposes three simple tools.\n\n###  1. search_services\n\nUse this to find the right service.\n\n\n\n    search_services({ query: \"accounting invoice\" })\n\n\nExample response:\n\n\n\n    freee: AAA grade, high success rate, API/MCP support\n    QuickBooks: A grade, API-first\n    Xero: BBB grade, community MCP available\n\n\nThe useful part is that services are ranked by how easy they are for agents to actually connect to.\n\nNot by marketing claims.\n\nNot by popularity.\n\nBy agent connection signals.\n\n###  2. lookup\n\nUse this before writing code.\n\n\n\n    lookup({ service_id: \"freee-accounting\", detail: true })\n\n\nExample response:\n\n\n\n    Auth:\n      OAuth 2.0 + PKCE\n\n    Rate limit:\n      300 requests / 5 min\n\n    Required:\n      company_id\n\n    Gotchas:\n      - PKCE is mandatory\n      - company_id must be fetched first\n      - some endpoint versions are easy to confuse\n\n\nThis is the main value.\n\nClaude gets the connection map before it starts coding.\n\n###  3. report\n\nOptional, but useful.\n\n\n\n    report({\n      service_id: \"freee-accounting\",\n      success: true\n    })\n\n\nOr:\n\n\n\n    report({\n      service_id: \"freee-accounting\",\n      success: false,\n      reason: \"OAuth scope mismatch\"\n    })\n\n\nThis helps improve the connection data over time.\n\n##  Why not just read the docs?\n\nYou should read the docs.\n\nBut when working with coding agents, there are three practical problems.\n\n###  1. Model knowledge is stale\n\nClaude or GPT may know an older version of an API.\n\nThat is enough to cause a bad first implementation.\n\n###  2. Docs are long\n\nThe answer might be in the docs, but buried across multiple pages:\n\n  * auth\n  * scopes\n  * rate limits\n  * object IDs\n  * endpoint versions\n  * sandbox behavior\n  * write permissions\n\n\n\nIf you make the agent read everything from scratch, you may burn tokens before writing any useful code.\n\n###  3. MCP-specific issues are not in vendor docs\n\nThis is the biggest one.\n\nA direct API call may work, but an MCP server may fail because:\n\n  * the MCP server is outdated\n  * only read operations are supported\n  * write operations have lower success rates\n  * OAuth scopes are handled differently\n  * the server wraps the API in a non-obvious way\n\n\n\nVendor docs usually do not cover that.\n\nAgent connection data does.\n\n##  What it covers\n\nKanseiLINK currently includes connection data for 11,000+ SaaS and API services.\n\nSome examples:\n\n\n\n    Accounting:\n      freee\n      QuickBooks\n      Xero\n      MYOB\n\n    CRM:\n      Salesforce\n      HubSpot\n      Sansan\n\n    HR:\n      BambooHR\n      SmartHR\n      Gusto\n\n    Dev tools:\n      GitHub\n      GitLab\n      Jira\n      Linear\n\n    Other:\n      Slack\n      Notion\n      Stripe\n      Twilio\n\n\nEach service has a grade from AAA to C.\n\n\n\n    AAA: likely to work smoothly\n    A: usable with minor care\n    BBB: some friction expected\n    BB: expect issues\n    C: difficult to connect\n\n\nThis is not a rating of the product.\n\nIt is a rating of how easy it is for an AI agent to discover, understand, connect, and execute against that service.\n\n##  Setup\n\nClaude Code:\n\n\n\n    claude mcp add kansei-link -- npx @kansei-link/mcp-server\n\n\nClaude Desktop:\n\n\n\n    {\n      \"mcpServers\": {\n        \"kansei-link\": {\n          \"command\": \"npx\",\n          \"args\": [\"@kansei-link/mcp-server\"]\n        }\n      }\n    }\n\n\nGitHub:\n\n\n\n    https://github.com/kansei-link/kansei-mcp-server\n\n\n##  Takeaway\n\nWhen Claude Code struggles with SaaS API integration, the problem is often not code generation.\n\nIt is the starting context.\n\nIf the agent starts with stale API assumptions, you pay for retries.\n\nIf the agent starts with a current connection guide, it writes better code sooner.\n\nThat is the whole trick:\n\n> Give the agent the map before asking it to drive.\n\nIf you are using Claude Code, Cursor, or any AI coding agent for SaaS API integration, this can save real tokens and real time.",
  "title": "Stop letting Claude guess your SaaS API auth flow"
}