MCP とカーソル: IDE をデータベースと API に接続します。
IDE に PostgreSQL データベース、クエリの問題への直接アクセスを要求できることを想像してください。 GitHub で開いたり、Confluence からドキュメントを読んだり、外部 REST API を呼び出したりすることがすべて、離れることなく実行できます。 エディターから、データやパターンを手動でコピーして貼り付ける必要はありません。これは SF ではありません。まさにその通りです を許可します モデルコンテキストプロトコル (MCP) カーソルに統合されています。
MCP は、Anthropic によって開発され、2024 年 11 月に発表されたオープン標準であり、 この言語は、構造化され、安全かつ構成可能な方法で外部システムと通信できます。数か月後には、 AI と開発ツールの統合の事実上の標準となっています: Cursor がそれを採用しました 現在、エコシステムには、データベース、API、ファイル システム、 発券システムなど。
この記事では、アーキテクチャ、構成という実用的かつ高度な観点から MCP を詳しく掘り下げます。 カーソル、最も一般的なユースケース向けに事前構築されたサーバー、TypeScript でのカスタム サーバーの作成、 セキュリティとトラブルシューティング。完了すると、Cursor を有能なエージェントに変えるために必要なものがすべて揃います。 プロジェクトのインフラストラクチャ全体と対話します。
この記事で学べること
- MCP アーキテクチャ: ホスト、クライアント、サーバー、ツール、リソース、プロンプト
- ファイルを使用して Cursor に MCP を設定します
.cursor/mcp.json(プロジェクトとグローバルスコープ) - MCP サーバー経由で Cursor を PostgreSQL、MySQL、SQLite に接続します
- REST API、GraphQL、GitHub、Jira を事前構築された MCP サーバーと統合
- 公式 SDK を使用して TypeScript でカスタム MCP サーバーを作成する
- セキュリティ、権限、資格情報のローテーションを管理する
- 最も一般的な MCP 接続の問題を診断して修正します
- MCP と従来の統合アプローチの比較
前提条件
- IDE カーソルがインストールされています (安定した MCP にはバージョン 0.43 以降を推奨)
- Node.js 18 以降と npm がインストールされている
- TypeScript と JSON の基本的な知識
- オプション: 実用的な例として、アクセス可能な PostgreSQL または MySQL データベース
1. モデルコンテキストプロトコルとは
Il モデルコンテキストプロトコル (MCP) そして、以下を定義する JSON-RPC 2.0 に基づくオープン標準 AI アプリケーションのように ( クライアント) 外部システム (i サーバ) のための 構造化された方法でコンテキストを取得し、アクションを実行し、リソースにアクセスします。そしてその「共通言語」とは、 Cursor は、GitHub、Jira と通信するのと同じ方法でデータベースと通信できるようになります。 またはその他の API。
MCP が登場する前は、各 AI IDE は独自の独自の統合を実装していました。さまざまなツール、さまざまな API、 さまざまなフォーマット。 MCP を使用すると、一度作成したサーバーが Cursor、Claude Desktop、VS Code Copilot で動作します およびその他の互換性のあるクライアント。これは、HTTP を Web 標準にしたのと同じ原理です。
2. MCP アーキテクチャ: ホスト、クライアント、サーバー
MCP アーキテクチャは 3 つのレベルに分かれており、何かを設定する前に理解することが不可欠です。 統合:
3 つの MCP レベル
- ホスト: ユーザーが直接対話するアプリケーション。この場合はカーソル IDE。 ホストは MCP クライアントのライフサイクルを管理し、AI モデルとの対話を調整します。
- MCP クライアント: 単一のホストとの 1:1 接続を維持するホストの内部コンポーネント。 MCPサーバー。 Cursor は各サーバーのクライアントの作成とメンテナンスを自動的に管理します 設定されています。
- MCPサーバー: ツール、リソース、プロンプトなどの機能を公開する外部 (またはリモート) プロセス。 ローカル プロセス (stdio) またはリモート サービス (HTTP/SSE) の場合があります。
各 MCP サーバーは、クライアントが使用できる 3 種類のプリミティブを公開します。
// Primitive MCP: overview concettuale
// 1. TOOLS - azioni che il modello può invocare
// (lettura/scrittura, chiamate API, esecuzione query)
{
"name": "execute_query",
"description": "Esegue una query SQL sul database",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" }
},
"required": ["query"]
}
}
// 2. RESOURCES - dati che il modello può leggere
// (simili a endpoint GET di una REST API)
{
"uri": "postgres://mydb/tables",
"name": "Database Tables",
"description": "Lista di tutte le tabelle del database",
"mimeType": "application/json"
}
// 3. PROMPTS - template riutilizzabili
// (istruzioni pre-costruite per task comuni)
{
"name": "analyze_schema",
"description": "Analizza lo schema del database e suggerisce ottimizzazioni",
"arguments": [
{ "name": "table_name", "required": true }
]
}クライアントとサーバー間の通信は、サポートされているトランスポートのいずれかを介して JSON-RPC 2.0 経由で行われます。
- stdio (標準 I/O): クライアントはサーバーを子プロセスとして起動し、 標準入力/標準出力。ローカルサーバーにとって最もシンプルで最適なトランスポートです。カーソルが自動的に管理します プロセスのライフサイクル。
- ストリーミング可能なHTTP: サーバーは独立した HTTP サービスとして実行されます。リモートサーバーに最適 複数の開発者間で共有したり、クラウド統合のために共有したりできます。 2025 年 3 月以降、SSE に代わって輸送手段として使用されています。 HTTP を推奨します。
SSE トランスポートの非推奨化
Server-Sent Events (SSE) トランスポートは、2025 年 3 月 26 日の MCP 仕様によって非推奨になりました。あなたがそうであれば
既存の SSE 構成を使用して、次の形式に移行します streamableHttp。カーソルバージョン
0.43+ は新しい仕様をサポートします。
3. カーソルで MCP を設定する
カーソルは、構成されたサーバーが利用できる場所を決定する 2 つの MCP 構成スコープをサポートします。
# Configurazione GLOBALE (disponibile in tutti i progetti)
~/.cursor/mcp.json
# Configurazione PROGETTO (solo nel workspace corrente)
.cursor/mcp.json <-- nella root del progetto
# La configurazione progetto ha PRIORITA su quella globale
# in caso di conflitti di nomi構成ファイルの基本構造はシンプルで、2 つのスコープ間で一貫しています。
// .cursor/mcp.json - Struttura base
{
"mcpServers": {
"nome-server": {
"command": "comando-da-eseguire",
"args": ["argomento1", "argomento2"],
"env": {
"VARIABILE": "valore"
}
}
}
}HTTP 経由のリモート サーバーの場合、構造は少し異なります。
// .cursor/mcp.json - Server remoto HTTP
{
"mcpServers": {
"nome-server-remoto": {
"url": "https://mio-server-mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer {{env.MCP_API_TOKEN}}"
}
}
}
}
設定ファイルを保存した後、Cursor を再起動するか、 を押します。 Cmd/Ctrl + Shift + P そして検索してください
「MCP: Reload Servers」を実行して変更を適用します。サーバーのステータスを確認できます
設定 > MCP 各サーバーが緑色 (接続済み) または赤色 (エラー) のインジケーターで表示されます。
4. データベース用 MCP サーバー
MCP データベース サーバーは、開発者にとって最も有用なものの 1 つです。MCP データベース サーバーを使用すると、Cursor AI モデルで以下のことが可能になります。 スキーマの検査、クエリの実行、パフォーマンスの分析、構造ベースの最適化の提案 一般的な仮定に基づいたものではなく、データベースの現実性を確認します。
4.1 ポストグレSQL
Anthropic の PostgreSQL 用の公式 MCP サーバーは、データベース スキーマを MCP リソースとして公開し、 読み取り専用クエリを実行するには (セキュリティのため読み取り専用):
// .cursor/mcp.json - PostgreSQL server ufficiale
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://utente:password@localhost:5432/mio_database"
]
}
}
}構成ファイルに認証情報を含めないでください
ファイル内の接続文字列 URL にユーザー名とパスワードを直接入力しないでください。
mcp.json特にファイルが git でバージョン管理されている場合。環境変数を使用します。
// .cursor/mcp.json - PostgreSQL con variabili d'ambiente
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres"
],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://{{env.DB_USER}}:{{env.DB_PASSWORD}}@localhost:5432/mio_database"
}
}
}
}
# Nel tuo .env (NON versionato):
DB_USER=myuser
DB_PASSWORD=supersecretpassword構成が完了すると、カーソル チャットからデータベースと直接対話できるようになります。
PostgreSQL MCP を使用したプロンプトの例
- 「users テーブルのスキーマを見せて、重要なインデックスが欠落していないか教えてください。」
- 「先月に作成された注文テーブルには何行ありますか?」
- 「この遅いクエリを分析し、実際のスキーマに基づいて最適化を提案します。」
- 「TypeORM 移行を生成して、email_verified 列を users テーブルに追加します」
4.2 MySQL と MariaDB
MySQL と MariaDB については、同様の機能を提供するコミュニティ MCP サーバーがあります。
// .cursor/mcp.json - MySQL tramite server community
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "@benborla29/mcp-server-mysql"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "password",
"MYSQL_DB": "mio_database",
"ALLOW_INSERT_OPERATION": "false",
"ALLOW_UPDATE_OPERATION": "false",
"ALLOW_DELETE_OPERATION": "false"
}
}
}
}4.3 ローカル開発用の SQLite
// .cursor/mcp.json - SQLite (ottimo per sviluppo locale e test)
{
"mcpServers": {
"sqlite": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sqlite",
"--db-path",
"./database/dev.db"
]
}
}
}5. API および外部サービス用の MCP サーバー
MCP エコシステムは、データベースに加えて、最も一般的なツールをワークフローに統合するための事前構築済みサーバーを提供します。 日々の発展の様子。
5.1 GitHub MCP
公式 GitHub MCP サーバー (GitHub によって直接維持される) を使用すると、リポジトリを管理できます。 問題、プル リクエスト、CI/CD ワークフローなどを Cursor チャットから直接行えます。
// .cursor/mcp.json - GitHub MCP ufficiale (via Docker)
// NOTA: Il package npm e stato deprecato ad aprile 2025
// Usa l'immagine Docker ufficiale:
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}
// Alternativa: via npx (versione community)
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}GitHub サーバーを構成すると、Cursor は次のことが可能になります。
- 問題とプルリクエストの読み取りと作成
- コミット履歴を分析してバグのコンテキストを理解する
- パブリックおよびプライベートリポジトリのコードを検索する
- GitHub アクション ワークフローをトリガーする
- PR に関するコメントを読み書きする
5.2 MCP ファイルシステム
Anthropic のファイルシステム サーバーを使用すると、モデルは特定のパスに対してファイルの読み取りと書き込みを行うことができます。 きめ細かなアクセス制御を使用すると、次のようになります。
// .cursor/mcp.json - Filesystem con accesso limitato
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/federicocalo/progetti",
"/tmp/cursor-workspace"
]
}
}
}
// ATTENZIONE: specifica SOLO le directory necessarie
// Non dare accesso a / (root) o home directory completa5.3 マルチサーバー構成
MCP in Cursor の強力な側面と、複数のサーバーを一度に構成できる機能です。 データベース、外部 API、内部ツールを 1 つのファイルに結合します。
// .cursor/mcp.json - Configurazione completa multi-server
{
"mcpServers": {
// Database principale
"postgres-prod": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:pass@prod-db:5432/app"
}
},
// Database di sviluppo
"postgres-dev": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/app_dev"
}
},
// Repository GitHub
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
}
},
// Filesystem progetti
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/federicocalo/progetti/mio-app"
]
},
// Server custom interno
"api-interna": {
"command": "node",
"args": ["/Users/federicocalo/mcp-servers/api-server/dist/index.js"],
"env": {
"API_BASE_URL": "https://api.mia-azienda.com",
"API_KEY": "key_xxxx"
}
}
}
}6. TypeScript でカスタム MCP サーバーを作成する
事前に構築されたサーバーは多くの一般的なユースケースをカバーしますが、多くの場合、Cursor をシステムに接続する必要があります。 内部、独自の API、またはプロジェクト固有のロジック。公式の TypeScript SDK では、 驚くほど簡単なカスタムサーバーの作成。
6.1 プロジェクトのセットアップ
# Inizializza il progetto
mkdir mio-mcp-server
cd mio-mcp-server
npm init -y
# Installa le dipendenze
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node ts-node
# Configura TypeScript
npx tsc --init --target ES2022 --module commonjs --outDir dist// package.json - scripts necessari
{
"name": "mio-mcp-server",
"version": "1.0.0",
"main": "dist/index.js",
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "ts-node src/index.ts"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0",
"zod": "^3.22.0"
},
"devDependencies": {
"typescript": "^5.3.0",
"@types/node": "^20.0.0",
"ts-node": "^10.9.0"
}
}6.2 基本的な MCP サーバーとツールおよびリソース
内部 REST API をクエリするツールを公開する完全な MCP サーバーを構築する方法を見てみましょう 静的データを公開するためのリソース:
// src/index.ts - Server MCP completo
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
const API_BASE_URL = process.env.API_BASE_URL || "https://api.esempio.com";
const API_KEY = process.env.API_KEY || "";
// Inizializza il server MCP
const server = new Server(
{
name: "mio-server-mcp",
version: "1.0.0",
},
{
capabilities: {
resources: {},
tools: {},
},
}
);
// === TOOLS ===
// I tools sono azioni che il modello può invocare
// Lista i tools disponibili
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "get_utenti",
description: "Recupera la lista degli utenti attivi dall'API",
inputSchema: {
type: "object",
properties: {
limite: {
type: "number",
description: "Numero massimo di utenti da restituire (default: 10)",
},
ruolo: {
type: "string",
enum: ["admin", "user", "guest"],
description: "Filtra per ruolo utente",
},
},
required: [],
},
},
{
name: "crea_report",
description: "Genera un report aggregato per un periodo specificato",
inputSchema: {
type: "object",
properties: {
data_inizio: {
type: "string",
format: "date",
description: "Data inizio periodo (YYYY-MM-DD)",
},
data_fine: {
type: "string",
format: "date",
description: "Data fine periodo (YYYY-MM-DD)",
},
tipo: {
type: "string",
enum: ["vendite", "utenti", "performance"],
description: "Tipo di report da generare",
},
},
required: ["data_inizio", "data_fine", "tipo"],
},
},
],
};
});
// Gestisce l'esecuzione dei tools
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case "get_utenti": {
const limite = (args?.limite as number) || 10;
const ruolo = args?.ruolo as string | undefined;
const url = new URL(`${API_BASE_URL}/utenti`);
url.searchParams.set("limite", String(limite));
if (ruolo) url.searchParams.set("ruolo", ruolo);
const response = await fetch(url.toString(), {
headers: { "X-API-Key": API_KEY },
});
if (!response.ok) {
throw new Error(`API error: ${response.status} ${response.statusText}`);
}
const data = await response.json();
return {
content: [
{
type: "text",
text: JSON.stringify(data, null, 2),
},
],
};
}
case "crea_report": {
const { data_inizio, data_fine, tipo } = args as {
data_inizio: string;
data_fine: string;
tipo: string;
};
const response = await fetch(`${API_BASE_URL}/report`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": API_KEY,
},
body: JSON.stringify({ data_inizio, data_fine, tipo }),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(`Errore report: ${response.status} - ${errorText}`);
}
const report = await response.json();
return {
content: [
{
type: "text",
text: `Report generato con successo:\n${JSON.stringify(report, null, 2)}`,
},
],
};
}
default:
throw new Error(`Tool sconosciuto: ${name}`);
}
});
// === RESOURCES ===
// Le resources espongono dati statici o semi-statici
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "config://ambiente",
name: "Configurazione Ambiente",
description: "Configurazione corrente dell'ambiente applicativo",
mimeType: "application/json",
},
{
uri: "docs://api-endpoints",
name: "Documentazione API",
description: "Lista di tutti gli endpoint API disponibili",
mimeType: "text/markdown",
},
],
};
});
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
switch (uri) {
case "config://ambiente":
return {
contents: [
{
uri,
mimeType: "application/json",
text: JSON.stringify(
{
ambiente: process.env.NODE_ENV || "development",
api_base_url: API_BASE_URL,
versione_api: "v2",
funzionalità: {
report: true,
export_csv: process.env.ENABLE_CSV === "true",
},
},
null,
2
),
},
],
};
case "docs://api-endpoints":
return {
contents: [
{
uri,
mimeType: "text/markdown",
text: `# Endpoint API Disponibili
## Utenti
- GET /utenti - Lista utenti
- GET /utenti/:id - Dettaglio utente
- POST /utenti - Crea utente
## Report
- POST /report - Genera report
- GET /report/:id - Scarica report
## Autenticazione
Tutti gli endpoint richiedono l'header X-API-Key.`,
},
],
};
default:
throw new Error(`Risorsa non trovata: ${uri}`);
}
});
// Avvia il server con trasporto stdio
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
// Log su stderr (non stdout) per non corrompere il protocollo
console.error("Server MCP avviato e in ascolto");
}
main().catch((error) => {
console.error("Errore fatale:", error);
process.exit(1);
});6.3 カスタムサーバーをカーソルに接続する
// Prima compila il server
// npm run build
// .cursor/mcp.json - Registra il server custom
{
"mcpServers": {
"api-interna": {
"command": "node",
"args": ["/percorso/assoluto/mio-mcp-server/dist/index.js"],
"env": {
"API_BASE_URL": "https://api.mia-azienda.com",
"API_KEY": "chiave_segreta_qui",
"NODE_ENV": "production"
}
}
}
}ヒント: 絶対パスを使用する
フィールドで args ファイルの mcp.json、常にファイルへの絶対パスを使用します
サーバーの。カーソルは、作業ディレクトリが存在しない可能性があるコンテキストで MCP プロセスを実行します。
あなたが期待していること。
7. MCP 認証情報のセキュリティと管理
セキュリティはおそらく、専門的な状況で MCP を実装する際に最も重要な側面です。 MCP サーバーは機密リソース (データベース、API、ファイルシステム) および構成ミスにアクセスできます。 重要なデータが漏洩する可能性があります。
7.1 最小特権の原則
基本原則は、各 MCP サーバーを必要最小限の権限で構成することです。
// SBAGLIATO: credenziali admin sul database
{
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://postgres:adminpassword@localhost/db"
]
}
}
// CORRETTO: utente dedicato in sola lettura
// Prima crea l'utente sul database:
// CREATE USER cursor_readonly WITH PASSWORD 'password';
// GRANT CONNECT ON DATABASE db TO cursor_readonly;
// GRANT USAGE ON SCHEMA public TO cursor_readonly;
// GRANT SELECT ON ALL TABLES IN SCHEMA public TO cursor_readonly;
{
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://cursor_readonly:password@localhost/db"
]
}
}7.2 環境変数の安全な管理
// APPROCCIO 1: Variabili d'ambiente di sistema
// Imposta le variabili nell'ambiente shell prima di avviare Cursor
# ~/.zshrc o ~/.bashrc
export POSTGRES_URL="postgresql://user:pass@localhost/db"
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
// Nel mcp.json usa i riferimenti alle variabili:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_URL": "${POSTGRES_URL}"
}
}
}
}
// APPROCCIO 2: File .env locale (NON committato)
// .cursor/mcp.json legge automaticamente le variabili
// dall'ambiente del processo Cursor, che a sua volta
// può essere configurato da un .env nel progetto
// APPROCCIO 3: Secret manager (produzione/team)
// Usa 1Password CLI, Vault o AWS Secrets Manager:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_URL": "op://vault/database/connection-string"
}
}
}
}7.3 CVE-2025-54136: MCPoison と mcp.json のセキュリティ
2025 年に、Cursor に影響を与える「MCPoison」（CVE-2025-54136）と呼ばれる脆弱性が文書化されました。
MCP サーバーがユーザーによって承認されると、Cursor は信頼を 名前
サーバーの 指示。ファイル mcp.json 攻撃者によって変更された
共有リポジトリは、同じ信頼できる名前を維持しながら、実行されたコマンドを置き換えることができます。
MC毒軽減対策
- コミットしないでください
.cursor/mcp.json共有リポジトリ内の認証情報を使用して - 追加
.cursor/mcp.jsonal.gitignore資格情報が含まれている場合 - グローバル構成を使用する (
~/.cursor/mcp.json) 個人認証情報用 - Cursor を定期的に更新します。新しいバージョンでは信頼管理が向上します。
- 必ず内容を確認してください
mcp.json共有リポジトリからプルした後
# .gitignore - Aggiungi questa riga
.cursor/mcp.json
# Oppure usa un file template senza credenziali:
# .cursor/mcp.json.example (versionato, senza segreti)
# .cursor/mcp.json (ignorato da git, con segreti reali)8. MCP 接続のトラブルシューティング
MCP は比較的新しいテクノロジーであり、特に接続中に問題が発生することがよくあります。 初期設定。ここでは、最も頻繁に発生する問題を診断して解決するための体系的なガイドを示します。
8.1 サーバーのステータスを確認する
最初のステップは常に、カーソル UI からサーバーのステータスを確認することです。
- 開ける 設定 (Cmd/Ctrl + ,)
- セクションに移動 MCP サイドパネルに
- 各サーバーにはインジケーターが表示されます: 緑 (接続中)、黄 (接続中)、赤 (エラー)
- エラー メッセージを表示するには、障害が発生したサーバーの横にあるログ アイコンをクリックします。
8.2 一般的な問題と解決策
// PROBLEMA 1: "Server non trovato" o "command not found"
// CAUSA: Il comando npx/node non e nel PATH di Cursor
// SOLUZIONE: Usa il percorso assoluto del comando
// SBAGLIATO:
{ "command": "npx", "args": ["-y", "@mcp/server-postgres"] }
// CORRETTO (trova il percorso con 'which npx'):
{ "command": "/usr/local/bin/npx", "args": ["-y", "@mcp/server-postgres"] }
// ---
// PROBLEMA 2: "Connection refused" o "ECONNREFUSED"
// CAUSA: Il server SSE non e in esecuzione o porta sbagliata
// SOLUZIONE: Verifica che il server sia avviato e usa il trasporto corretto
// Per server stdio, non serve nessun server avviato separatamente
// Cursor lo avvia automaticamente come processo figlio
// ---
// PROBLEMA 3: JSON malformato nel mcp.json
// CAUSA: Virgola finale, commenti JS, ecc.
// MCP.json e JSON standard: NO commenti, NO trailing commas
// SOLUZIONE: Valida il JSON con jq:
// cat .cursor/mcp.json | jq .
// ---
// PROBLEMA 4: Variabili d'ambiente non disponibili
// CAUSA: Cursor non eredita le variabili dell'ambiente shell
// SOLUZIONE: Specifica esplicitamente le variabili nel campo "env"
{
"env": {
"MY_VAR": "valore-diretto"
}
}
// ---
// PROBLEMA 5: Output su stdout corrompe il protocollo
// CAUSA: Il server MCP usa console.log() invece di console.error()
// SOLUZIONE: Usa SEMPRE console.error() per i log nei server stdio
// Il protocollo MCP usa stdout per i messaggi JSON-RPC
// Qualsiasi output non-JSON su stdout rompe la comunicazione8.3 MCP デバッグを有効にする
# Modalità debug per MCP in Cursor
# Avvia Cursor da terminale con debug abilitato:
cursor --enable-mcp-logging --log-level=DEBUG
# Variabili d'ambiente per debug del server MCP:
export MCP_DEBUG=1
export MCP_LOG_LEVEL=debug
export DEBUG="mcp:*"
# Testa il server MCP manualmente (fuori da Cursor):
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | node dist/index.js9. MCP と従来のアプローチの比較
MCP の真の価値を理解するには、従来の統合アプローチと比較することが役立ちます。 AI と外部ツールの間:
| 待ってます | 従来のアプローチ | MCP |
|---|---|---|
| 統合 | スキーマ/データを手動でコピーしてチャットに貼り付けます | リアルタイムでの直接かつ構造化されたアクセス |
| 標準化 | すべての IDE には互換性のない独自のプラグインが含まれています | 1 つのサーバーがすべての MCP クライアントで動作します |
| 安全性 | プロンプトまたはチャット コンテキスト内の認証情報 | サーバー プロセス内の認証情報。モデルには公開されません。 |
| 構成可能性 | 分離された統合、組み合わせるのが難しい | 複数のサーバーを単一のワークフローに組み合わせることができます |
| メンテナンス | 維持する必要があるカスタム統合 | コミュニティサーバーエコシステムの維持 |
| データ更新 | (静的) コンテキスト内の静的データ | 更新されたデータへのライブアクセス |
10. 実践的なワークフロー: Angular プロジェクトを使用した MCP
MCP が PostgreSQL バックエンドを使用した Angular プロジェクトの開発ワークフローをどのように変換するかを見てみましょう。 複数のサーバーを単一の運用構成に結合します。
// .cursor/mcp.json - Configurazione per progetto Angular + PostgreSQL
{
"mcpServers": {
"database": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://cursor_ro:pass@localhost:5432/angular_app"
]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
}
}
}
}この構成をアクティブにすると、Cursor で使用できるプロンプトがさらに強力になります。
MCP マルチサーバーによる高度なプロンプト
- 「GitHub の問題 #142 を見て、要求された機能を実装してください。データベース スキーマは次のとおりです。」 postgres/my_db、関係するテーブルはサブスクリプションと呼ばれます。」
- 「UserList コンポーネントの E2E テストを作成します。実際のデータベース スキーマを使用して生成します 現実的なテストデータです。」
- 「コミット abc1234 でリグレッションが発生しました。現在のスキーマとそのスキーマを比較してください」 以前を確認し、問題の原因となった可能性のある変更を特定します。」
- "TypeORM 移行ファイルを生成して、必要な列を users テーブルに追加します。 現在のデータベース構造に基づいています。」
11. 運用環境における MCP のベスト プラクティス
開発チーム用の MCP チェックリスト
- 部屋の区切り: 開発、ステージング、運用に異なる MCP サーバーを使用します。 同じ MCP サーバーが複数の環境を指すことはありません
- デフォルトでは読み取り専用: すべてのデータベース サーバーを読み取り専用として構成します。 専用サーバー上でのみ書き込みを可能にし、二重確認を行うことができます。
- キーのローテーション: MCP サーバーが使用する API トークンの有効期限を設定します。 60 ～ 90 日が良い習慣です
-
mcp.json の Gitignore: 資格情報を使用してファイルをバージョン管理することはありません。アメリカ合衆国
mcp.json.example共有テンプレートとして - 監視： 追跡のためにカスタムサーバーに構造化ログを実装する どのツールがどのカーソルセッションから呼び出されるのか
- タイムアウト: それを防ぐために、サーバーの API 呼び出しにタイムアウトを追加します。 カーソルは無限に待機します
- 入力の検証: Zod などを使用して、受け取ったパラメータを検証します 操作を実行する前にツールから
// Esempio: Tool con validazione Zod e timeout
import { z } from "zod";
const QuerySchema = z.object({
tabella: z.string().min(1).max(100).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/),
limite: z.number().int().positive().max(1000).default(50),
filtro: z.string().optional(),
});
// Nel handler del tool:
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const parsed = QuerySchema.safeParse(request.params.arguments);
if (!parsed.success) {
throw new Error(`Parametri non validi: ${parsed.error.message}`);
}
// AbortController per timeout
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout
try {
const result = await fetch(apiUrl, {
signal: controller.signal,
headers: { "X-API-Key": API_KEY },
});
return { content: [{ type: "text", text: await result.text() }] };
} finally {
clearTimeout(timeoutId);
}
});結論
モデル コンテキスト プロトコルは、AI IDE がどのように対話するかにおける質的な飛躍を表しています。 開発インフラ。静的で一般的な情報を単独で扱うのではなく、 MCP が設定されたカーソルは、実際のコンテキスト (スキーマ) について推論できるエージェントになります。 データベースの現在のステータス、GitHub 上の未解決の問題、プロジェクトの特定の構成。
MCP をグローバルとプロジェクト レベルの両方で構成する方法、事前に構築されたサーバーを使用する方法について見てきました。 最も一般的なユースケース (PostgreSQL、GitHub、ファイルシステム) について、TypeScript でカスタム サーバーを構築する方法 独自のシステムを統合する方法、および専門的な方法でセキュリティとトラブルシューティングを管理する方法。
自然な次のステップは、MCP と Cursor の他の高度な機能を組み合わせることであり、MCP を使用します。 エージェント モード内で、エージェントにアクセスを必要とする複数ステップの操作を実行させます。 データベースとリポジトリ。パターンを含む複雑な機能を計画するには計画モードを使用します 移行とアプリケーション コードを一緒に実行します。可能性は大きく広がります。
MCP エコシステムは急速に成長しています。新しいサーバーは毎週 npm で公開され、 公式 Anthropic リポジトリにあります。カタログを定期的に調べて調べてみる価値があります ワークフローを高速化できる新しい統合。
このシリーズの関連記事
関連シリーズ
- MCP シリーズ (ID 64 ～ 77): モデル コンテキスト プロトコルに関する徹底的な研究を完了し、 すべての MCP クライアント向けの高度なアーキテクチャと実装
- 最新の Angular (ID 224 ～ 233): プロフェッショナルな Angular ワークフローを実現 この記事で紹介されている MCP 統合による機能強化
- バイブコーディング (ID 281 ～ 288): 開発に対する AI ファーストのアプローチは完璧です MCP での Cursor の高度な使用を補完します。