Nhost

Nhost MCP サービス

Nhost MCP サービスは、あらゆる Nhost プロジェクトにエージェント型インターフェースを追加します。プロジェクトの GraphQL API を MCP（Model Context Protocol） サーバーとして公開し、Claude、Cursor などの AI アシスタントや、MCP に対応したクライアントがデータを照会・変更できるようにします。

Nhost で開発している場合、このサービスを使うと、カスタムの統合コードを用意することなく、ユーザーが AI アシスタントを通じてプロジェクトのデータを操作できます。プロジェクトと並行してデプロイすれば、MCP に対応したクライアントが接続し、既存の Nhost Auth 設定を使ってユーザーに代わって認証を行い、定義済みの権限の範囲内でデータを扱えます。

仕組み

MCP サーバーは、AI アシスタントと Nhost プロジェクトの GraphQL API の間に位置します。アシスタントから呼び出せる次の 3 つのツールを提供します。

• get-schema - GraphQL スキーマをイントロスペクションし、アシスタントがデータモデルを理解できるようにします。利用可能な操作の概要、または指定したクエリ／ミューテーションの完全な SDL を返します。
• graphql-query - プロジェクトに対して読み取り専用の GraphQL クエリを実行します。
• graphql-mutation - データの作成、更新、削除を行う GraphQL ミューテーションを実行します。

起動時にサーバーは GraphQL エンドポイントからスキーマの概要を取得し、MCP の指示に含めます。これにより、追加の設定なしで AI アシスタントはデータモデルをすぐに把握できます。

OAuth2 による認証

MCP サービスは Nhost Auth と連携し、MCP 認証仕様に準拠した OAuth2 認可サーバーとして機能します。これにより、OAuth2 に対応した MCP クライアントは、Nhost プロジェクトで自動的に認証できます。

フローは次のとおりです。

1. MCP クライアントは、MCP サーバーから /.well-known/oauth-protected-resource を取得して、認証要件を検出します。
2. クライアントはユーザーを Nhost Auth の認可エンドポイントにリダイレクトし、ログインさせます（PKCE を使用した認可コードフロー）。
3. 認証後、クライアントは認可コードを JWT アクセストークンと交換します。
4. 以降のすべての MCP リクエストには、Bearer トークンとして JWT が含まれます。
5. MCP サーバーは JWKS を使って JWT の署名を検証し、発行者と有効期限を確認したうえで、すべての GraphQL リクエストにトークンを転送します。
6. GraphQL サービスは JWT のクレームに基づいて行レベルおよび列レベルの権限を適用するため、AI アシスタントは認証済みユーザーに許可されたデータのみアクセスできます。

重要！CIMD を有効にする必要があります。

特定のロールの強制

--enforce-role フラグを指定すると、x-hasura-default-role クレームが指定したロールと一致するトークンのみを MCP サーバーが受け付けるように制限できます。デフォルトロールが異なるリクエストには、403 Forbidden レスポンスが返されます。

たとえば、--enforce-role=user_mcp を設定すると、デフォルトロールが user_mcp のトークンのみが受け付けられます。そのロールに制限付きの権限（たとえば、特定のテーブルに対する読み取り専用権限）を設定している場合、AI アシスタントに適用される権限もそれに制限されます。

これにより、次のことができます。

• AI アクセス用に、制限付き権限を持つ専用ロール（例：user_mcp）を作成できます。
• AI アシスタントにはデータの読み取りを許可し、変更は許可しないようにできます。
• アシスタントに表示するテーブルや列を制限できます。
• 用途ごとに異なるロール設定で、複数の MCP インスタンスを実行できます。

設定

すべてのフラグは環境変数で設定できます。

フラグ	環境変数	説明
--listen-addr	MCP_LISTEN_ADDR	HTTP リッスンアドレス（デフォルト：:3000）
--debug	MCP_DEBUG	デバッグログを有効にします
--log-format-text	MCP_LOG_FORMAT_TEXT	ログを JSON ではなくプレーンテキスト形式にします
--graphql-endpoint	MCP_GRAPHQL_ENDPOINT	GraphQL エンドポイント URL（必須）
--mcp-instructions	MCP_INSTRUCTIONS	サーバーレベルの MCP 指示
--query-instructions	MCP_QUERY_INSTRUCTIONS	graphql-query ツールの指示
--mutation-instructions	MCP_MUTATION_INSTRUCTIONS	graphql-mutation ツールの指示
--schema-instructions	MCP_SCHEMA_INSTRUCTIONS	get-schema ツールの指示
--auth-url	MCP_AUTH_URL	OAuth2 認可サーバー URL（必須）
--realm	MCP_REALM	WWW-Authenticate ヘッダーのレルム
--enforce-role	MCP_ENFORCE_ROLE	JWT のデフォルト Hasura ロールがこの値と一致するよう強制します
--browser-html	MCP_BROWSER_HTML	ブラウザーがサービス URL にアクセスしたときに配信する HTML コンテンツ

Nhost へのデプロイ

Nhost Run にデプロイするには、以下のワンクリックインストールリンクを使用できます。

https://app.nhost.io/run-one-click-install?config=eyJuYW1lIjoibWNwIiwiaW1hZ2UiOnsiaW1hZ2UiOiJuaG9zdC9tY3A6MC4xLjAiLCJwdWxsQ3JlZGVudGlhbHMiOm51bGx9LCJjb21tYW5kIjpbIm1jcCJdLCJyZXNvdXJjZXMiOnsiY29tcHV0ZSI6eyJjcHUiOjEyNSwibWVtb3J5IjoyNTZ9LCJzdG9yYWdlIjpbXSwicmVwbGljYXMiOjEsImF1dG9zY2FsZXIiOm51bGx9LCJlbnZpcm9ubWVudCI6W3sibmFtZSI6Ik1DUF9BVVRIX1VSTCIsInZhbHVlIjoiaHR0cHM6Ly9TVUJET01BSU4uYXV0aC5SRUdJT04ubmhvc3QucnVuL3YxIn0seyJuYW1lIjoiTUNQX1JFQUxNIiwidmFsdWUiOiJodHRwczovL21jcC5hY21lLmNvbSJ9LHsibmFtZSI6Ik1DUF9HUkFQSFFMX0VORFBPSU5UIiwidmFsdWUiOiJodHRwOi8vaGFzdXJhLXNlcnZpY2U6ODA4MC92MS9ncmFwaHFsIn0seyJuYW1lIjoiTUNQX0lOU1RSVUNUSU9OUyIsInZhbHVlIjoiVGhlc2UgYXJlIHNvbWUgaW5zdHJ1Y3Rpb25zIGZvciB5b3VyIE1DUCBzZXJ2ZXIuIn0seyJuYW1lIjoiTUNQX0VORk9SQ0VfUk9MRSIsInZhbHVlIjoidXNlcl9tY3AifV0sInBvcnRzIjpbeyJwb3J0IjozMDAwLCJ0eXBlIjoiaHR0cCIsInB1Ymxpc2giOnRydWV9XSwiaGVhbHRoQ2hlY2siOm51bGx9

必要に応じて編集してください。MCP_AUTH_URL に正しいサブドメインとリージョンを設定し（独自ドメインを使用している場合はそのドメインを設定）、MCP_REALM に MCP サービスで使用する URL を設定してください。また、必要に応じて MCP_INSTRUCTIONS を変更し、MCP_ENFORCE_ROLE を変更または削除してください。

注：サービスの最新バージョンを使用していることを確認するため、リリースページを確認してください。

または、プロジェクトディレクトリに run-mcp.toml を追加します。

name = 'mcp'
command = ['mcp']

[image]
image = 'nhost/mcp:0.1.0'

[[environment]]
name = 'MCP_AUTH_URL'
value = 'https://local.auth.local.nhost.run/v1'

[[environment]]
name = 'MCP_REALM'
value = 'https://myapp.example.com'

[[environment]]
name = 'MCP_GRAPHQL_ENDPOINT'
value = 'http://hasura-service:8080/v1/graphql'

[[environment]]
name = 'MCP_INSTRUCTIONS'
value = 'This MCP server interacts with my application'

[[environment]]
name = 'MCP_ENFORCE_ROLE'
value = 'user_mcp'

[[ports]]
port = 3000
type = 'http'
publish = true

[resources]
replicas = 1

[resources.compute]
cpu = 125
memory = 256

その後、通常どおりプロジェクトをデプロイします。MCP サーバーは公開ポートで利用可能になり、MCP 互換クライアントで接続できます。

次のコマンドでローカル環境でも試すことができます。

nhost up --run-service run-mcp.toml

MCP クライアントの接続

MCP クライアントにサーバー URL を指定します。たとえば、Claude Desktop の設定では次のようにします。

1. 「カスタマイズ」→「コネクタ」に移動します
2. + をクリックし、任意の名前と、MCP サーバーが配置されている URL（例：https://mcp.acme.com）を入力します
3. 「追加」をクリックします
4. 接続すると、OAuth2 クライアントを認可するため、OAuth2 の同意ページにリダイレクトされます