Stop letting Claude guess your SaaS API auth flow

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

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

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

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" })

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

Then it can ask for the actual connection details.

lookup({ service_id: "salesforce-crm", detail: true })

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

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 })

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

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.

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" })

Example response:

freee: AAA grade, high success rate, API/MCP support

QuickBooks: A grade, API-first

Xero: BBB grade, community MCP available

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 })

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

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

})

Or:

report({

  service_id: "freee-accounting",

  success: false,

  reason: "OAuth scope mismatch"

})

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

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

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

Claude Desktop:

{

  "mcpServers": {

    "kansei-link": {

      "command": "npx",

      "args": ["@kansei-link/mcp-server"]

    }

  }

}

GitHub:

https://github.com/kansei-link/kansei-mcp-server

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.