DEV Community

michielinksee
michielinksee

Posted on

Stop letting Claude guess your SaaS API auth flow

#api #claude #llm #saas

The problem

Claude Code is great at writing integration code.

But when I ask it to connect to a SaaS API, the same annoying pattern keeps showing up:

Write auth code
↓
Call the API
↓
Auth error
↓
Fix the scope
↓
Missing required parameter
↓
Fix again
↓
Wrong endpoint version
↓
Try again
Enter fullscreen mode Exit fullscreen mode

By the time it works, I have burned thousands of tokens.

This happens a lot with SaaS APIs like Salesforce, HubSpot, Stripe, Slack, freee, SmartHR, kintone, and others.

The issue is not that Claude cannot write code.

The issue is that Claude often starts with stale assumptions.

SaaS APIs change all the time:

  • OAuth flows get updated
  • PKCE becomes required
  • API versions change
  • required parameters get added
  • rate limits change
  • official docs get reorganized
  • MCP servers behave differently from direct API calls

If the agent starts with the wrong connection assumptions, everything after that becomes a retry loop.

So I tried a simple fix:

Before letting Claude write API integration code, give it a connection guide.

The idea

Instead of asking Claude to connect directly to a SaaS API, I added an MCP server that tells Claude how to connect first.

claude mcp add kansei-link -- npx @kansei-link/mcp-server
Enter fullscreen mode Exit fullscreen mode

No API key.

No auth.

No setup beyond that.

Now the flow looks like this:

Before:
User → Claude → SaaS API
              ↑
        guessing from stale knowledge

After:
User → Claude → KanseiLINK MCP → connection guide
              ↓
           SaaS API
Enter fullscreen mode Exit fullscreen mode

The goal is not to make Claude “smarter”.

The goal is to stop Claude from guessing.

Example: Salesforce

Before writing code, Claude can ask KanseiLINK what it should know about the service.

search_services({ query: "salesforce crm" })
Enter fullscreen mode Exit fullscreen mode

Example response:

Salesforce
- Grade: BB
- Agent connection success rate: 43%
- Connection type: third-party MCP / API
- Auth: OAuth 2.0
- Known issues:
  - complex scope configuration
  - instance URL varies by org
  - API version must be specified
Enter fullscreen mode Exit fullscreen mode

Then it can ask for the actual connection details.

lookup({ service_id: "salesforce-crm", detail: true })
Enter fullscreen mode Exit fullscreen mode

Example response:

Auth:
  OAuth 2.0

Common pitfalls:
  - instance URL varies per org
  - API version must be specified
  - third-party MCP servers may not support all write operations
  - Bulk API has different requirements
Enter fullscreen mode Exit fullscreen mode

That context is small, but it changes the output a lot.

Claude starts from the right assumptions instead of writing a plausible but outdated integration.

Example: freee accounting

Another example:

lookup({ service_id: "freee-accounting", detail: true })
Enter fullscreen mode Exit fullscreen mode

Example response:

Auth:
  OAuth 2.0 + PKCE

Required:
  company_id

Common pitfalls:
  - PKCE is required
  - company_id must be fetched before posting transactions
  - endpoint versions are easy to confuse
  - missing scopes cause auth failures
Enter fullscreen mode Exit fullscreen mode

This is exactly the kind of information that prevents a 3-turn debugging loop.

Before vs after

I tested this on a few common SaaS integration tasks.

This is not a formal benchmark, but I tracked token usage and retries in my own Claude Code workflow.

Task Before After Reduction
Salesforce opportunity update ~5,500 tokens ~1,800 tokens 67%
HubSpot contact creation ~3,400 tokens ~1,200 tokens 65%
Stripe invoice generation ~2,800 tokens ~1,100 tokens 61%
Slack webhook setup ~2,100 tokens ~900 tokens 57%

On average, this reduced token usage by around 60–70%.

The savings mostly came from removing failed retries.

The lookup itself is cheap.

A failed retry is expensive.

The MCP tools

KanseiLINK MCP currently exposes three simple tools.

1. search_services

Use this to find the right service.

search_services({ query: "accounting invoice" })
Enter fullscreen mode Exit fullscreen mode

Example response:

freee: AAA grade, high success rate, API/MCP support
QuickBooks: A grade, API-first
Xero: BBB grade, community MCP available
Enter fullscreen mode Exit fullscreen mode

The useful part is that services are ranked by how easy they are for agents to actually connect to.

Not by marketing claims.

Not by popularity.

By agent connection signals.

2. lookup

Use this before writing code.

lookup({ service_id: "freee-accounting", detail: true })
Enter fullscreen mode Exit fullscreen mode

Example response:

Auth:
  OAuth 2.0 + PKCE

Rate limit:
  300 requests / 5 min

Required:
  company_id

Gotchas:
  - PKCE is mandatory
  - company_id must be fetched first
  - some endpoint versions are easy to confuse
Enter fullscreen mode Exit fullscreen mode

This is the main value.

Claude gets the connection map before it starts coding.

3. report

Optional, but useful.

report({
  service_id: "freee-accounting",
  success: true
})
Enter fullscreen mode Exit fullscreen mode

Or:

report({
  service_id: "freee-accounting",
  success: false,
  reason: "OAuth scope mismatch"
})
Enter fullscreen mode Exit fullscreen mode

This helps improve the connection data over time.

Why not just read the docs?

You should read the docs.

But when working with coding agents, there are three practical problems.

1. Model knowledge is stale

Claude or GPT may know an older version of an API.

That is enough to cause a bad first implementation.

2. Docs are long

The answer might be in the docs, but buried across multiple pages:

  • auth
  • scopes
  • rate limits
  • object IDs
  • endpoint versions
  • sandbox behavior
  • write permissions

If you make the agent read everything from scratch, you may burn tokens before writing any useful code.

3. MCP-specific issues are not in vendor docs

This is the biggest one.

A direct API call may work, but an MCP server may fail because:

  • the MCP server is outdated
  • only read operations are supported
  • write operations have lower success rates
  • OAuth scopes are handled differently
  • the server wraps the API in a non-obvious way

Vendor docs usually do not cover that.

Agent connection data does.

What it covers

KanseiLINK currently includes connection data for 11,000+ SaaS and API services.

Some examples:

Accounting:
  freee
  QuickBooks
  Xero
  MYOB

CRM:
  Salesforce
  HubSpot
  Sansan

HR:
  BambooHR
  SmartHR
  Gusto

Dev tools:
  GitHub
  GitLab
  Jira
  Linear

Other:
  Slack
  Notion
  Stripe
  Twilio
Enter fullscreen mode Exit fullscreen mode

Each service has a grade from AAA to C.

AAA: likely to work smoothly
A: usable with minor care
BBB: some friction expected
BB: expect issues
C: difficult to connect
Enter fullscreen mode Exit fullscreen mode

This is not a rating of the product.

It is a rating of how easy it is for an AI agent to discover, understand, connect, and execute against that service.

Setup

Claude Code:

claude mcp add kansei-link -- npx @kansei-link/mcp-server
Enter fullscreen mode Exit fullscreen mode

Claude Desktop:

{
  "mcpServers": {
    "kansei-link": {
      "command": "npx",
      "args": ["@kansei-link/mcp-server"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

GitHub:

https://github.com/kansei-link/kansei-mcp-server
Enter fullscreen mode Exit fullscreen mode

Takeaway

When Claude Code struggles with SaaS API integration, the problem is often not code generation.

It is the starting context.

If the agent starts with stale API assumptions, you pay for retries.

If the agent starts with a current connection guide, it writes better code sooner.

That is the whole trick:

Give the agent the map before asking it to drive.

If you are using Claude Code, Cursor, or any AI coding agent for SaaS API integration, this can save real tokens and real time.

Top comments (0)