What authentication methods does the kintone MCP server support?

kintone supports three authentication methods: 1) API Token (recommended): generate a token in app settings and pass it in the X-Cybozu-API-Token header. 2) Password authentication: Base64-encode 'username:password' and pass in the X-Cybozu-Authorization header. 3) OAuth 2.0: requires app registration at developer.cybozu.io. For agent use cases, API Token is the simplest and recommended method.

Why are all kintone API field values wrapped in {value: '...'}?

This is a kintone API design choice. All field values are wrapped in object format ({value: 'actual value'}) — this applies to number fields, text fields, and all other types without exception. You must always access values via record.field_code.value.

What are kintone API's rate limits?

The standard plan has a limit of 10,000 requests per day. Concurrent connections are limited to 10. Use bulk operations (POST /records.json can insert up to 100 records at once) to reduce total request count when processing large data volumes.

Service Deep-Dive 2026-04-14 15 min read

kintone MCP Deep Dive — Behind the AAA Grade, Three Auth Methods & Developer Pitfalls

Cybozu’s kintone is one of the few Japan-made SaaS platforms that has earned an AAA grade in KanseiLink’s AEO evaluation. Its official MCP server is available in three deployment formats — npm, Docker, and Desktop Extension — and March 2026 brought new additions: a process management API and Desktop Extension support. Yet kintone’s API has idiosyncrasies that will reliably trip up agent developers on the first pass. This article uses KanseiLink’s data to thoroughly explain the rationale behind the AAA grade, how to choose between three authentication methods, and five pitfalls to navigate during implementation.

1. Why kintone Earns AAA

AAA

kintone MCP — AXR Rating Official MCP: ✅ (npm / Docker / Desktop Extension)
Auth: API Token / Password / OAuth 2.0
Last updated: 2026-04-13

KanseiLink’s AAA designation for kintone rests on three pillars:

Evaluation Criterion	kintone Performance	Rating
Official MCP Server	Officially by Cybozu (github.com/kintone/mcp-server); available as npm, Docker, and Desktop Extension	✅ Best-in-class
Auth Method Diversity	Supports three methods: API Token (simple), password auth, and OAuth 2.0	✅ Excellent
API Maturity	RESTful API v1 with pagination, bulk operations, and process management API	✅ Excellent
Update Cadence	Process management API (Mar 30, 2026) and Desktop Extension (Mar 10, 2026) added in March	✅ Active
Documentation Quality	Official Japanese and English documentation maintained at cybozu.dev	✅ Good

That said, the trust_score sits at 0.7 (out of 1.0). The reason: kintone’s idiosyncratic API design (the {value} wrapper and field code system discussed below) makes initial agent implementation difficult. The AAA grade reflects ecosystem maturity, not “easy to use immediately.” This distinction matters.

2. Three Authentication Methods — How to Choose

kintone supports three authentication methods. Here’s a practical guide for different agent development scenarios:

Recommended / Agent Use Cases

① API Token Authentication

The simplest authentication method. Generate a token per kintone app and pass it in the X-Cybozu-API-Token header. No complex OAuth flows required — ideal for agent implementations.

1 kintone admin panel → App Settings → API Token → "Add"
2 Check the required permissions (record read/add/edit) and generate the token
3 Send requests with header: X-Cybozu-API-Token: {generated_token}
4 For multiple apps, join tokens with a comma: token1,token2

Simple / Development Testing

② Password Authentication (Basic Auth)

Base64-encode username:password and set it in the X-Cybozu-Authorization header. Not recommended for production, but useful for rapid development testing.

1 Base64-encode username:password
2 Set header: X-Cybozu-Authorization: {base64_string}
3 Switch to API Token or OAuth for production environments

Advanced / Enterprise

③ OAuth 2.0 Authentication

The most secure method, with fine-grained user permission control. Scopes: k:app_record:read, k:app_record:write. Best suited for enterprise applications and multi-user systems.

1 Register an OAuth app at developer.cybozu.io
2 Authorization URL: https://{subdomain}.cybozu.com/oauth2/authorization
3 Token URL: https://{subdomain}.cybozu.com/oauth2/token
4 Set scopes: k:app_record:read k:app_record:write

3. Five Pitfalls Every Agent Developer Will Hit

⚠️ Pitfall 1: Every Field Value Is Wrapped in {value: ...}

kintone’s biggest trap. All field values in API responses are wrapped in object format: {"value": "actual_value"}. This applies to number fields, text fields — everything without exception. Always access values via record.field_code.value, never record.field_code.

      kintone API Response Example (Pitfall 1)
// kintone GET /k/v1/record.json response
{
  "record": {
    "$id": { "value": "42" },              // ID is also a string inside value
    "Title": { "value": "Project Alpha" }, // ✅ access via .value
    "Quantity": { "value": "100" },      // Numbers are returned as strings!
    "Assignee": {
      "value": [{ "code": "user1", "name": "Taro Yamada" }]
    }
  }
}

// ❌ Wrong: record.Quantity → undefined
// ✅ Right:  record.Quantity.value → "100" (string)
// ✅ Right:  parseInt(record.Quantity.value) → 100 (for numeric use)
    

⚠️ Pitfall 2: Field Codes and Display Names Are Different Things

kintone fields have both a “display name” (e.g., "Assignee Name") and a “field code” (e.g., assignee_name). API calls require field codes. Always call GET /k/v1/app/form/fields.json?app={app_id} first to retrieve the field code list before making data requests.

      Correct Sequence: Get Field Codes → Then Query Records
// Step 1: Retrieve field code list
const fieldsRes = await fetch(
  `https://${subdomain}.cybozu.com/k/v1/app/form/fields.json?app=${appId}`,
  { headers: { 'X-Cybozu-API-Token': apiToken } }
);
const { properties } = await fieldsRes.json();
// properties = { "Title": { type: "SINGLE_LINE_TEXT", code: "Title", label: "Deal Name" } }

// Step 2: Query records using field codes
const recordsRes = await fetch(
  `https://${subdomain}.cybozu.com/k/v1/records.json?app=${appId}&query=Status%3D"In+Progress"&totalCount=true`,
  { headers: { 'X-Cybozu-API-Token': apiToken } }
);
const { records, totalCount } = await recordsRes.json();
console.log(`Total: ${totalCount} records`); // totalCount is a string: "42"
    

⚠️ Pitfall 3: You Must Ask the User for Their Subdomain

kintone API base URLs follow the format https://{subdomain}.cybozu.com, requiring each company’s unique subdomain. There is no fixed universal API endpoint. Your agent implementation must either prompt users to enter their subdomain or configure it in advance as an environment variable (KINTONE_SUBDOMAIN).

⚠️ Pitfall 4: 10,000 Requests/Day Limit + 10 Concurrent Connections

Standard plan limits: 10,000 requests per day and maximum 10 concurrent connections. Agents processing large record volumes must leverage bulk operations (POST /records.json accepts up to 100 records at once) to maximize throughput per request. Managing concurrency is equally critical.

💡 Best Practice: Minimize Request Count with Bulk Operations

Instead of POSTing records one by one, batch up to 100 records in a single POST. This theoretically enables up to 1 million record operations per day within the 10,000 request limit.

      Bulk Insert — Up to 100 Records at Once
// ✅ Bulk insert (up to 100 records)
const records = Array.from({ length: 100 }, (_, i) => ({
  Title: { value: `Task ${i + 1}` },
  Status: { value: "Not Started" },
}));

const res = await fetch(
  `https://${subdomain}.cybozu.com/k/v1/records.json`,
  {
    method: 'POST',
    headers: {
      'X-Cybozu-API-Token': apiToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ app: appId, records }),
  }
);
// → { "ids": ["1","2",...,"100"], "revisions": ["1","1",...,"1"] }
    

⚠️ Pitfall 5: Query Syntax Resembles SQL but Is Proprietary

kintone’s query syntax is SQL-like but proprietary. Key rules: string values must be in double quotes (Status = "In Progress"), URL encoding is required, you must add totalCount: true to get total record counts, and ORDER BY/LIMIT/OFFSET are available for pagination.

      kintone Query Syntax Reference
// Pagination (100 records at a time)
`/k/v1/records.json?app=${appId}&query=Status%20%3D%20"In+Progress"%20order%20by%20updated_time%20desc%20limit%20100%20offset%200&totalCount=true`

// Compound conditions
`query=Status%20%3D%20"Completed"%20and%20Assignee%20in%20("user1")%20and%20DueDate%20%3C%20"2026-04-30"`

// Key rules:
// - String values use "double quotes" (no single quotes)
// - in operator: field_code in ("val1", "val2")
// - totalCount=true required to get the total count
// - Default limit=100, max limit=500
    

4. The Cybozu Dual-Stack: Combining kintone and Garoon

kintone and Garoon (Cybozu’s enterprise groupware) share the same API Token authentication format and X-Cybozu-API-Token header pattern. This makes the “Cybozu dual-stack” — where a single agent manages records in kintone while simultaneously checking schedules and approving workflows in Garoon — a natural integration rather than an engineering challenge.

Function	kintone MCP	Garoon MCP
Record management (CRM, project tracking, etc.)	✅ /k/v1/records.json	—
Schedule & calendar	—	✅ /g/api/v1/schedule/events
Workflow approvals	✅ /k/v1/record/status.json (process management)	✅ /g/api/v1/workflow/requests
Bulletin boards & announcements	—	✅ /g/api/v1/bulletin
Authentication format	API Token / OAuth2	API Token (same format)

Conclusion — kintone Is AAA, but It Requires Preparation

kintone’s MCP ecosystem is among the most complete in the Japanese SaaS landscape. The official MCP server in three deployment formats, three authentication methods, and an API that covers bulk operations, process management, and workflow automation form a powerful foundation for business process automation.

However, without understanding kintone’s idiosyncratic design — the {value} wrapper and field code system — you will reliably lose hours on the first implementation. Understanding the five pitfalls documented here before starting will dramatically cut your ramp-up time.

As real agent telemetry for kintone (success rates, latency distributions, error patterns) accumulates in KanseiLink’s dataset, we will update the AEO score dynamically. The latest score is always available through the links below.

Check kintone’s Latest AEO Score

Real-time success rate, latency, and Agent Voice data are available in the consulting plan.

Request Data Access