API & MCP アクセス

API & MCP アクセス

Metricgram には公開 API と MCP サーバーがあり、独自のツール、ダッシュボード、自動化、AI クライアントを、アカウントで利用できるデータや操作に接続できます。

MCP サーバーは すべての有料プラン で利用でき、14日間の無料トライアル中も使えます。AI クライアントは OAuth（サーバー URL を貼り付けてアクセスを承認）または API トークンで接続できます。REST API には Elite アクセスが必要です。アカウントに含まれていない場合、API セクションはロック表示またはアップグレード案内になることがあります。

場所

管理画面で 連携 > MCP または 連携 > API を開きます。アクセス権のあるアカウントでは、API トークンの作成、有効なトークンの確認、失効、プランで利用できる技術リファレンスの確認ができます。

トークンの仕組み

• トークンは特定のグループではなく、あなたの Metricgram ユーザーアカウントに紐づきます。
• トークンは、そのアカウントが管理できるグループとリソースにアクセスできます。
• トークンには、グループ、メンバー、メッセージ、自動化、購読者、分析、サポートチケット、紹介、MCP などの権限が含まれます。
• 一部の endpoint はデータの読み取りのみですが、権限によっては作成、更新、モデレーション、アクション実行もできます。
• トークン値は作成時に一度だけ表示されます。安全な場所に保管してください。

MCP経由のTelegram Bot API

MCPサーバーはグループ単位に限定されたTelegram Bot APIも公開しているため、AIエージェントはMetricgramボットまたはカスタムボットを通じてあなたのグループで操作できます。

• telegram_api_methods でトークンが呼び出せるメソッドを一覧表示し、telegram_bot_api で公式のBot APIパラメーターを使っていずれかを呼び出します。
• 日常業務は型付きツールでカバーできます：send_telegram_message、send_telegram_media、send_telegram_poll、pin_telegram_message、manage_forum_topic、create_telegram_invite_link など。
• 対象のチャットは常に自分のグループのいずれかです。chat_id を渡す必要はなく、Metricgramが group_id から導き出します。
• Telegramの操作には専用のスコープがあります：telegram:read、telegram:write、telegram:moderate、telegram:admin。これらのスコープ導入前に作成したトークンで使うには、トークンを作り直す必要があります。
• メディアは公開されたHTTPSのURLまたはTelegramの file_id である必要があり、インラインボタンはURLを開くかテキストをコピーすることしかできません。
• 書き込み系ツールは任意の idempotency_key に対応しているため、リトライした呼び出しが二重に実行されることはありません。

認証と制限

API リクエストでは Authorization: Bearer mg_... ヘッダーを使用します。デフォルトの上限はトークンごとに 1 分あたり 600 リクエストで、フォームからアプリで許可された範囲内の値を選択できます。

トークンを安全に使う

トークンの権限によっては書き込みやモデレーションも行えるため、接続先に必要な権限だけを付与し、トークン値を公開しないでください。使わなくなったトークンは管理画面から失効できます。

トークンが失効した場合、アカウントが API アクセスを失った場合、またはプランに API & MCP が含まれなくなった場合、そのトークンを使ったリクエストは拒否されます。

推奨事項

• 外部ツールごとに別々のトークンを作成します。
• どこで使っているか分かる明確な名前を付けます。
• 不要になったトークンは失効します。
• チャット、スクリーンショット、チケット、公開リポジトリでトークンを共有しないでください。