いつもの AI チャットが、
そのまま管理画面になる

空室

• 部屋ごとの入居中／空室の別、空室になった日、空室日数
• 入居率サマリー（総戸数・入居戸数・空室戸数・入居率）
• 空室メモ（募集状況の覚え書き）の閲覧と更新

契約

• 契約の一覧・詳細（家賃・管理費・敷金・契約期間・契約状態）
• 家賃改定や契約期間延長などの条件更新
• 退去処理（退去日を指定すると空室化し、以降の請求が取り消される）
• 新規入居受付の開始（氏名の入力は AI ではなく大家ご本人がブラウザで行います）

請求・入金

• 月次の請求一覧（請求額・入金額・未収額・入金状態・滞納フラグis_overdue）
• 入金の記録（入金日・金額・支払方法）
• 入金状態の一括切替（入金済にする／未入金に戻す）

運営コスト

• 修繕費・保険料・固定資産税・水道光熱費・管理組合費などの一覧
• コストの登録・編集（毎月／毎年の定期計上にも対応）

資金繰り

• 日繰り表（日ごとの入出金予定と手元現金残高の推移）
• 入出金予定の追加・編集・削除、実績化
• 手元現金残高の更新
• 預り金（敷金）サマリー
• 月別の収支集計（収入・支出・純収益・空室戸数）

資金繰り関連は、家族アカウントのfamily_memberロールで発行したトークンからは参照も操作もできません（ブラウザ画面での権限と揃えてあります）。

入居者は「201号室さん」として扱われる

AI から見た入居者は、氏名ではなく部屋のラベルです。物件名がわかる場合は物件名込みで"さくらハイツ 201号室さん"、物件名が取れない場合のみ"201号室さん"となります。誰の話をしているかは大家さんには一目でわかり、AI にとっては匿名のままです。

歴代の入居者の区別も、氏名ではなく契約のstatus（有効／退去予定／解約／満了）と、契約どうしをつなぐparent_contract_idのチェーンで行います。「前の入居者」を指すのに氏名は必要ありません。

3 層で守っています

1. そもそも DB から読まない（コンパイル時ガード）
   契約の参照は、氏名系の暗号化カラム（*_enc）を SELECT しない専用の読み取り関数（listContractsForPublicApi / getContractForPublicApi）を使います。レスポンスを組み立てる関数の入力型に個人情報のフィールドが存在しないため、「うっかり氏名を混ぜる」コードは型エラーになって書けません。復号関数を import することも禁止しています。
2. 返す項目は許可リストで明示的に組み立てる
   「これは除外する」という denylist 方式は、項目が増えたときに漏れます。大家One は逆に、返してよい項目だけを 1 つずつ書き並べて出力を作ります。DB に新しいカラムが増えても、自動的に外へ出ることはありません。
3. 返す直前にもう一度検査する
   すべてのレスポンスは、送出直前にassertNoPiiを通ります。*_enc で終わるキーや、tenant_name / phone / address / guarantor / account_number といった禁止キーが 1 つでも含まれていたら、レスポンスを返さずエラーにします。MCP 経由の場合は、委譲先の公開API と MCP 層で計 2 回この検査を通ります。

書き込む側も止めます

入居受付ドラフト作成（POST /move-in-drafts / start_move_in_draft）は、AI が気を利かせて氏名を送ってきても受け付けません。氏名・フリガナ・電話・メール・住所・生年月日・保証人・同居人・勤務先などを思わせるキーが含まれていると、422 PII_NOT_ALLOWEDで拒否します。

このときのエラーメッセージにはキー名しか載せません。値をそのまま返すと、拒否したはずの個人情報がエラーレスポンスやログに残ってしまうためです。

取得できないもの・取得できるもの

なお金額は一切マスクしていません。家賃も残高も実額で返ります。守っているのは「誰か」であって「いくらか」ではない、という割り切りです。

入居受付だけは個人情報をまたぎます — その渡し方

新しい入居者の登録だけは、どうしても氏名が要ります。ここは AI に氏名を渡さずに済むよう、署名付きの短命リンクを大家さんに手渡す方式にしています。

1. AI が start_move_in_draft を呼ぶ。渡すのは部屋ID・家賃・契約期間など、個人情報でない項目だけ。
2. サーバーが draft_id / url / expires_at を返す。
3. AI はその URL を大家さんに案内する。大家さんが自分のブラウザで開いて氏名などを入力する。

URL は <サイトURL>/move-ins/new?draft=<署名付きトークン> の形で、有効期限は 30 分です。署名は HMAC-SHA256、署名対象に含まれるのはdraft_id / owner_id / exp の3 値だけで、個人情報は含まれません。改ざん検知のための署名であり、リンクを開いても中に氏名は入っていません。

ステップ 1: アクセストークン（PAT）を発行する

トークンの発行は、大家One にログインして［設定］→［API連携］タブから行います。ここが唯一の発行経路です。トークン発行 API 自体はブラウザのセッション認証専用なので、PAT を使ってさらに PAT を発行することはできません（トークンが漏れても増殖しない設計です）。

発行画面では次を選びます。

• 有効期限： 無期限 / 30日 / 90日 / 180日 / 1年
• スコープ： そのトークンに許す操作の範囲（下表）。必要最小限を選んでください。

発行すると平文のトークンが表示されます。表示されるのは発行直後の 1 回だけで、あとから再表示はできません。サーバー側には bcrypt ハッシュしか残らないため、運営側でも復元できません。控え忘れたら、失効させて発行し直してください。

トークンの形式

ooya_pat_<lookup 12桁><secret 32桁>   ← 全長 53 文字

例: ooya_pat_a1B2c3D4e5F6gHiJkLmNoPqRsTuVwXyZ0123456789ab

先頭 ooya_pat_ は固定の目印、続く 12 桁は検索キー、残る 32 桁が秘密部分です。GitHub の ghp_ と同じ発想で、誤ってリポジトリに混入したときに grep で見つけられるようにしています。

スコープ一覧

まとめて指定したい場合は、ワイルドカードread:*（参照系すべて）とwrite:*（操作系すべて）も選べます。スコープが足りないエンドポイントを呼ぶと403 INSUFFICIENT_SCOPE が返ります。

発行者のロールもトークンに焼き込まれます。家族アカウントのfamily_memberロールで発行したトークンは参照専用で、さらに資金繰り系の 6 エンドポイントは実行時にも403 ROLE_FORBIDDENで遮断されます（read:cashflow はそもそも発行時に選べません）。

ステップ 2: クライアントを設定する

大家One の MCP サーバーはStreamable HTTP のみで提供しています（stdio 方式・SSE 方式には対応していません）。エンドポイントと認証は次のとおりです。

POST https://www.ooyaone.com/api/mcp
Authorization: Bearer ooya_pat_...
Content-Type: application/json

リモート MCP に対応しているクライアントの場合

URL と HTTP ヘッダを指定できるクライアントであれば、次の形の設定で接続できます。設定ファイルの場所やキー名はクライアントごとに異なりますので、お使いの製品のドキュメントを必ずご確認ください。

{
  "mcpServers": {
    "ooya-one": {
      "type": "http",
      "url": "https://www.ooyaone.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ooya_pat_あなたのトークン"
      }
    }
  }
}

リモート MCP に対応していないクライアントの場合

ローカルプロセス（stdio）しか起動できないクライアントでは、mcp-remote のようなブリッジを間に挟む形になります。ブリッジ側がリモートの Streamable HTTP エンドポイントへ中継します。

{
  "mcpServers": {
    "ooya-one": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.ooyaone.com/api/mcp",
        "--header", "Authorization: Bearer ooya_pat_あなたのトークン"
      ]
    }
  }
}

ステップ 3: 動作を確認する

MCP は initialize / ping / tools/list もすべて PAT が必須です（未認証ではツール一覧すら取得できません）。まずはtools/list で 23 件返ってくるかを見るのが確実です。

curl -X POST https://www.ooyaone.com/api/mcp \
  -H "Authorization: Bearer $OOYA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

REST API 側の疎通は次のとおりです。

curl "https://www.ooyaone.com/api/public/v1/properties" \
  -H "Authorization: Bearer $OOYA_PAT"

# => {"data":[{"id":"...","name":"さくらハイツ","room_count":8}]}

401 が返る場合はトークンの綴り・失効・期限切れを確認してください。403 が返る場合は、レスポンスの code で原因を切り分けます。

• INSUFFICIENT_SCOPE … そのエンドポイントに必要なスコープをトークンが持っていない
• ROLE_FORBIDDEN … family_member ロールで資金繰り系を呼んだ
• ACCOUNT_SUSPENDED / ACCOUNT_CANCELLED / OWNER_SETUP_REQUIRED … アカウント側の状態が原因です。スコープの設定を見直しても解決しません

特に ACCOUNT_SUSPENDED（一時停止）と ACCOUNT_CANCELLED（退会済み）は、認証の直後・スコープ判定より前に検査されるため、スコープの内容にかかわらずすべてのエンドポイントが 403 になります。支払いの遅延などでアカウントが停止していないか、まず大家One にログインしてご確認ください。

サーバー情報

サーバーが AI に伝えている利用指針

initialize の instructions として、次の内容をそのまま返しています。個人情報を渡さないよう、接続直後に AI へ明示するためのものです。

大家One（賃貸物件管理）の運営データを操作するツール群です。
物件・部屋・空室・契約・請求（家賃入金）・運営コスト・資金繰りを参照し、入金記録や退去処理などの日々の運営操作を行えます。
入居者は「201号室さん」のように部屋番号で表され、氏名・電話番号・住所などの個人情報はこのサーバーでは一切取得も更新もできません。
ユーザーから個人情報を含む依頼（氏名の登録・変更など）を受けた場合は、ツールに個人情報を渡さず、start_move_in_draft が返す入力リンクを案内するか、大家本人が画面で操作するよう伝えてください。
操作の前にまず一覧系ツール（list_properties / list_rooms / list_contracts / list_invoices）で対象の ID を特定してください。

参照ツール（11）

操作ツール（12）

ツール実行の結果と JSON-RPC エラー

tools/call が成功すると、公開API と同じ{ "data": ... }（ページングがある場合は meta 付き）を JSON 文字列にしたテキストが content に入り、isError: false になります。ツール実行時のエラーはisError: true のテキスト（エラー: メッセージ（code: CODE））として返り、JSON-RPC としては成功扱いです。

なお MCP 経由と REST 直叩きでは、レート制限の消費（tools/call は IP 枠を 2 消費）と 422 の返り方だけが異なります。認証・スコープ認可・ロールガード・PII 非送出ガードは同じコードを通ります。

一方、プロトコル層で失敗した場合は JSON-RPC エラーになります。独自コードは次のとおりです。

共通事項

ページネーション

ページングに対応しているのは /contracts と /invoices の 2 つだけです。それ以外のエンドポイントは全件を返し、meta も付きません。小規模（1〜3 棟・数十契約）を想定した割り切りです。

• page： 1 始まり。既定は 1
• per_page： 既定 20、上限 100（範囲外は丸められます）

GET https://www.ooyaone.com/api/public/v1/invoices?month=2026-07&page=1&per_page=20

{
  "data": [ ... ],
  "meta": { "total": 42, "page": 1, "per_page": 20, "total_pages": 3 }
}

レート制限

3 つの枠が同時に効きます。いずれも 1 分のウィンドウです。書き込み系は、トークン単位 60 req/min に加えて書き込み専用枠が追加で適用されます。

超過時のレスポンスは次のとおりです。

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1784620800

{"error":"レート制限を超過しました","code":"RATE_LIMITED"}

MCP 経由は IP 枠を 2 つ消費します（重要）

tools/call を 1 回実行すると、IP 単位の枠が 2 消費されます。MCP 層が委譲前に 1 回チェックし（未認証のまま有効なツール名や必須引数を列挙されるのを防ぐため）、委譲先の公開API が同じキーでもう 1 回チェックするためです。両者は同一のキー空間（クライアント IP ＋ User-Agent のハッシュ）を使うので、MCP 経由の実効スループットは IP 枠の上では REST 直叩きの半分（既定 120 req/min → 実質 60 回/分の tools/call）になります。

トークン単位（60 req/min）と書き込み別枠（20 req/min）は二重に消費されません。また initialize / ping / tools/list は IP・トークンとも 1 回ずつの消費です。大量に呼び出す予定がある場合は、この差を見込んでください。

エラー形式

エラーは { "error", "code" } で統一しています。スキーマ検証（Zod）で弾かれた 422 の場合のみ、原因を特定できるようdetails に issue の配列が付きます。

HTTP/1.1 422 Unprocessable Entity

{
  "error": "バリデーションエラー",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": ["amount"],
      "message": "..."
    }
  ]
}

正直に書いておきます：想定外の例外に起因する 500 は { "error": "サーバーエラーが発生しました" } のみで、code が付きません。クライアント側では code が常に存在する前提のコードを書かないでください。

MCP 経由では 422 の details が構造化されません

REST は details に issue の配列をそのまま返しますが、MCP 経由ではpath と message だけを抜き出した日本語テキストになり、配列としては返りません（先頭 10 件まで）。上の例と同じ状況なら、MCP では次のように届きます。

エラー: バリデーションエラー（amount: ...）（code: VALIDATION_ERROR）

これは意図的な仕様です。issue の received / input にはクライアントが送った値そのものが入り得るため、そのまま返すと AI が誤って渡した氏名などがエラーメッセージ経由で外へ出てしまいます。項目名と理由だけなら AI が自己修正でき、かつ値は漏れません。

エンドポイント一覧

パスはすべて https://www.ooyaone.com/api/public/v1 からの相対です。{id} は各リソースの UUID で、一覧系エンドポイントのレスポンスから取得します。

PII 非送出は「フィルタ」ではなく「経路の不在」で担保する

個人情報の流出を防ぐ方法として真っ先に思いつくのは、レスポンス直前でマスクをかけることです。しかしその方式は「フィルタを書き忘れた新しいエンドポイント」で必ず破れます。

そこで大家One は、防御の重心を実行時から型システムに移しました。公開API 用の読み取り関数は氏名系カラムを SELECT せず、その戻り型を受け取るシリアライザは構造的に個人情報のフィールドを持ちません。氏名を返そうとするコードは、実行される前にコンパイルが通りません。

その上に、allowlist によるレスポンス構築（第 2 層）と、送出直前の assertNoPii（第 3 層）を重ねています。3 層とも独立していて、どれか 1 つが破れても他が止めます。

MCP は SDK を使わず、公開API へ内部委譲する

MCP サーバーの実装には SDK を使う選択肢もありましたが、採用しませんでした。理由は認証と PII ガードの地点を 1 つに保ちたかったからです。

大家One の MCP は独自の DB アクセスもビジネスロジックも持ちません。各ツールは、対応する公開API のルートハンドラを関数として直接呼びます（HTTP で自分自身を叩き直すことはしません）。その結果、PAT 認証・スコープ認可・レート制限・監査ログ・PII ガードは、MCP 経由でも REST 直叩きでもまったく同じコードを通ります。

SDK を挟むと、この「経路を増やさない」という性質を保つのが難しくなります。ツールが 23 個ある以上、認証を書き忘れる箇所が 23 個生まれる設計は避けたい、という判断です。

tools/call の前段だけは例外的に MCP 層で IP レート制限を先に通しています。ツール名の解決や引数の整形が無制限に実行できると、400 と 401 の応答差から有効なツール名や必須引数を列挙できてしまうためです。

ステートレス設計 — トークンを失効させたら次の 1 コールで効く

MCP サーバーは Mcp-Session-Id を発行しません。セッションを持たないので、すべてのリクエストが毎回フルの認証を通ります。

これは性能面では不利です（毎回 bcrypt が走ります）。それでも選んだのは、トークンを失効させた瞬間から、次の 1 コールで確実に遮断されるという性質を優先したからです。セッションをキャッシュすると、失効させたはずのトークンがセッションの生存期間だけ生き延びます。個人情報を扱うシステムで、その猶予は受け入れられないと考えました。

同じ理由で、トークンの失効・期限切れの判定は一切キャッシュせず毎回 DB を見ています。また、家族メンバーを除名してアクセスキーを失効させると、そのメンバーが発行済みの PAT も連鎖的に無効になります。

失敗するときは、開いたままにせず閉じる

レート制限の基盤（Redis）が設定されていない環境では、レート制限なしで公開API を動かすのではなく、503 を返します（PUBLIC_API_UNAVAILABLE）。「制限が効かないまま外に開いている」状態を作らないための fail-closed です。

認証エラーの理由を区別しないのも同じ考え方です。トークンが存在しないのか、期限切れなのか、失効済みなのかを返し分けると、それ自体が攻撃者への情報になります。すべて同じ401です。存在しないトークンでも、実在するトークンと同じだけの bcrypt 計算を行い、応答時間の差からトークンを推測されないようにしています。

自由記述欄の中身までは検査していません

assertNoPii が検査しているのはキー名だけで、値の中身は見ていません。したがって、大家さんご自身が

• 空室メモ（vacancy_memo）
• 運営コストの備考（memo）
• 日繰り予定の摘要（label）

に入居者や関係者の氏名・連絡先を書き込んでいた場合、それはそのまま API／MCP のレスポンスに含まれて返ります。仕組みで防ぎきれない部分なので、自由記述欄には個人が特定できる情報を書かない運用をお願いします。各ツールの説明文でも AI に対して同じ注意を伝えています。

個人情報の登録・変更は API からはできません

氏名・連絡先・保証人・同居人などの登録と変更は、公開API にも MCP にも経路がありません。update_contract で変更できるのは金額条件・期間・支払方法などに限られ、氏名系を渡すと422 になります。これらの変更は、大家さんご本人がブラウザ画面で行ってください。

トークンの発行は API からはできません

PAT の発行はブラウザの設定画面からのみです。CI などから自動でトークンを発行・ローテーションする使い方はできません。

MCP のトランスポートは 1 種類だけです

Streamable HTTP のみで、stdio 直結にも SSE にも対応していません。GET / DELETE は 405 を返します。サーバー起点の通知（listChanged 等）も送りません。JSON-RPC のバッチ（配列）も未対応です。

ページングがあるのは 2 エンドポイントだけです

/contracts と /invoices 以外は全件を返します。件数が多い場合の分割取得はできません。

入居率は 0〜1 の比率です

get_occupancy / GET /occupancy が返す occupancy_rate は、入居戸数 ÷ 総戸数 で計算した 0〜1 の小数です（8 戸中 6 戸入居なら 0.75）。パーセント値ではないので、表示する際は 100 倍してください。総戸数が 0 のときは 0 を返します。

CORS は既定で閉じています

ブラウザから直接呼び出す用途は想定していません。許可オリジンを明示設定しない限り、フロントエンドの JavaScript からは呼べません。そもそも PAT をブラウザに置く運用は避けてください。

本ページの設定例は動作保証ではありません

クイックスタートに掲載した MCP クライアントの設定例は、大家One 側の実装（Streamable HTTP ＋ Bearer 認証）から書き起こしたものであり、個別のクライアント製品での動作を検証したものではありません。接続がうまくいかない場合は、curl でサーバー側の疎通を確認したうえで、クライアント側の設定仕様をご確認ください。