MCP a kurzor: Připojte své IDE k databázi a rozhraní API
Představte si, že můžete požádat své IDE o přímý přístup k vaší databázi PostgreSQL, problémy s dotazy otevřít na GitHubu, číst dokumentaci z Confluence a volat externí REST API, to vše bez nutnosti odcházet z editoru a bez ručního kopírování a vkládání dat a vzorů. Není to sci-fi: přesně tak to je umožňuje Kontextový protokol modelu (MCP) integrované do kurzoru.
MCP je otevřený standard vyvinutý společností Anthropic a spuštěný v listopadu 2024, který definuje, jak modely jazyk může komunikovat s externími systémy strukturovaným, bezpečným a komponovatelným způsobem. Za několik měsíců a se stal de facto standardem pro integraci mezi AI a vývojovými nástroji: Cursor jej přijal nativně a dnes má ekosystém stovky připravených MCP serverů pro databáze, API, souborové systémy, systémy jízdenek a mnoho dalšího.
V tomto článku se ponoříme do MCP z praktického a pokročilého hlediska: architektura, konfigurace Kurzor, předpřipravený server pro nejběžnější případy použití, tvorba vlastních serverů v TypeScriptu, správa zabezpečení a odstraňování problémů. Až budete hotovi, budete mít vše, co potřebujete, abyste z Cursora udělali schopného agenta pro interakci s celou infrastrukturou vašeho projektu.
Co se dozvíte v tomto článku
- Architektura MCP: hostitel, klient, server, nástroje, prostředky a výzvy
- Nakonfigurujte MCP v kurzoru pomocí souboru
.cursor/mcp.json(projekt a globální rozsah) - Připojte kurzor k PostgreSQL, MySQL a SQLite přes MCP server
- Integrujte REST API, GraphQL, GitHub a Jira s předem sestavenými MCP servery
- Vytvořte vlastní MCP server v TypeScript s oficiální sadou SDK
- Spravujte zabezpečení, oprávnění a rotaci pověření
- Diagnostikujte a opravte nejběžnější problémy s připojením MCP
- Srovnání MCP a tradičních integračních přístupů
Předpoklady
- Nainstalovaný kurzor IDE (verze 0.43+ doporučená pro stabilní MCP)
- Node.js 18+ a npm nainstalovány
- Základní znalost TypeScript a JSON
- Volitelně: přístupná databáze PostgreSQL nebo MySQL pro praktické příklady
1. Co je to Model Context Protocol
Il Kontextový protokol modelu (MCP) a otevřený standard založený na JSON-RPC 2.0, který definuje jako aplikace AI ( klienta) lze připojit k externím systémům (tj server) pro získat kontext, provádět akce a přistupovat ke zdrojům strukturovaným způsobem. A ten "společný jazyk". umožňuje kurzoru mluvit s vaší databází stejným způsobem, jakým by mohl mluvit s GitHub, Jira nebo jakékoli jiné API.
Před MCP implementovalo každé AI IDE své vlastní proprietární integrace: různé nástroje, různá rozhraní API, různé formáty. S MCP funguje jednou napsaný server s Cursor, Claude Desktop, VS Code Copilot a jakýkoli jiný kompatibilní klient. Je to stejný princip, který udělal z HTTP webový standard.
2. Architektura MCP: hostitel, klient a server
Architektura MCP je rozdělena do tří úrovní, kterým je nezbytné porozumět před konfigurací čehokoli integrace:
Tři úrovně MCP
- Hostitelé: aplikace, se kterou uživatel přímo komunikuje. V tomto případě Cursor IDE. Hostitel spravuje životní cyklus klientů MCP a organizuje interakce s modely AI.
- Klienti MCP: vnitřní součást hostitele, která udržuje spojení 1:1 s jedním MCP server. Cursor automaticky spravuje vytváření a údržbu klientů pro každý server nakonfigurováno.
- Server MCP: externí (nebo vzdálený) proces, který odhaluje schopnosti: nástroje, zdroje a výzvy. Může to být místní proces (stdio) nebo vzdálená služba (HTTP/SSE).
Každý MCP server zpřístupňuje tři typy primitiv, které může klient použít:
// 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 }
]
}Komunikace mezi klientem a serverem probíhá prostřednictvím JSON-RPC 2.0 prostřednictvím jednoho z podporovaných přenosů:
- stdio (standardní I/O): klient spustí server jako podřízený proces a komunikuje prostřednictvím stdin/stdout. A nejjednodušší a nejvhodnější transport pro místní servery. Kurzor automaticky spravuje životní cyklus procesu.
- Streamovatelný HTTP: server běží jako nezávislá služba HTTP. Ideální pro vzdálené servery sdílené mezi více vývojáři nebo pro cloudové integrace. Od března 2025 nahradila SSE jako dopravu HTTP doporučeno.
Přeprava SSE ukončena
Přenos událostí odeslaných serverem (SSE) byl ukončen specifikací MCP z 26. března 2025. Pokud jste
pomocí stávajících konfigurací SSE migrujte na formát streamableHttp. Verze kurzoru
0.43+ podporuje novou specifikaci.
3. Nakonfigurujte MCP v kurzoru
Cursor podporuje dva rozsahy konfigurace MCP, které určují, kde jsou dostupné nakonfigurované servery:
# 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 nomiZákladní struktura konfiguračního souboru je jednoduchá a konzistentní mezi dvěma rozsahy:
// .cursor/mcp.json - Struttura base
{
"mcpServers": {
"nome-server": {
"command": "comando-da-eseguire",
"args": ["argomento1", "argomento2"],
"env": {
"VARIABILE": "valore"
}
}
}
}U vzdálených serverů přes HTTP je struktura mírně odlišná:
// .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}}"
}
}
}
}
Po uložení konfiguračního souboru restartujte kurzor nebo stiskněte Cmd/Ctrl + Shift + P a hledat
"MCP: Reload Servers" pro použití změn. Můžete zkontrolovat stav serverů v
Nastavení > MCP kde uvidíte každý server se zeleným (připojeno) nebo červeným (chyba) indikátorem.
4. Server MCP pro databázi
Databázové servery MCP patří mezi nejužitečnější pro vývojáře: umožňují model Cursor AI kontrolovat schémata, provádět dotazy, analyzovat výkon a navrhovat optimalizace založené na struktuře reality vaší databáze, nikoli na základě obecných předpokladů.
4.1 PostgreSQL
Oficiální MCP server pro PostgreSQL od Anthropic vystavuje schéma databáze jako MCP zdroje a umožňuje pro provádění dotazů pouze pro čtení (pouze pro čtení pro zabezpečení):
// .cursor/mcp.json - PostgreSQL server ufficiale
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://utente:password@localhost:5432/mio_database"
]
}
}
}Nevkládejte přihlašovací údaje do konfiguračního souboru
Nezadávejte své uživatelské jméno a heslo přímo do adresy URL připojovacího řetězce v souboru
mcp.json, zejména pokud má soubor verzi v git. Použít proměnné prostředí:
// .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=supersecretpasswordPo konfiguraci můžete s databází pracovat přímo z chatu kurzoru:
Prompt příklady s PostgreSQL MCP
- "Ukažte mi schéma tabulky uživatelů a řekněte mi, jestli chybí důležité indexy"
- "Kolik řádků je v tabulce objednávek vytvořených za poslední měsíc?"
- „Analyzujte tento pomalý dotaz a navrhněte optimalizace založené na skutečném schématu“
- "Vygenerujte migraci TypeORM pro přidání sloupce email_verified do tabulky uživatelů"
4.2 MySQL a MariaDB
Pro MySQL a MariaDB existují komunitní servery MCP, které nabízejí podobné funkce:
// .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 pro místní rozvoj
// .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. Server MCP pro rozhraní API a externí služby
Kromě databází nabízí ekosystém MCP předpřipravené servery pro integraci nejběžnějších nástrojů do pracovního postupu. každodenního vývoje.
5.1 GitHub MCP
Oficiální GitHub MCP server (spravovaný přímo GitHubem) vám umožňuje spravovat úložiště, problémy, žádosti o stažení, pracovní postupy CI/CD a mnoho dalšího přímo z chatu kurzoru:
// .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"
}
}
}
}S nakonfigurovaným serverem GitHub může Cursor:
- Čtěte a vytvářejte problémy a požadavky na stahování
- Analyzujte historii odevzdání, abyste pochopili kontext chyby
- Prohledejte kód veřejných a soukromých úložišť
- Spusťte pracovní postup akcí GitHub
- Čtěte a pište komentáře k PR
5.2 Souborové systémy MCP
Server souborového systému Anthropic umožňuje modelu číst a zapisovat soubory do konkrétních cest, s podrobným řízením přístupu:
// .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 Konfigurace více serverů
Výkonný aspekt MCP v Cursoru a možnost konfigurovat více serverů najednou, kombinace databází, externích rozhraní API a interních nástrojů v jediném souboru:
// .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. Vytvořte vlastní MCP server v TypeScript
Předpřipravené servery pokrývají mnoho běžných případů použití, ale často budete muset Cursor připojit k systémům interní, proprietární rozhraní API nebo logiku specifickou pro váš projekt. Oficiální TypeScript SDK vytváří Překvapivě jednoduchá tvorba vlastního serveru.
6.1 Nastavení projektu
# 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 Základní MCP Server s nástroji a zdroji
Podívejme se, jak vytvořit kompletní MCP server, který zpřístupní nástroje pro dotazování interního REST API a zdroje pro vystavení statických dat:
// 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 Připojte vlastní server ke kurzoru
// 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"
}
}
}
}Tip: Použijte Absolute Paths
V terénu args souboru mcp.json, vždy používejte absolutní cesty k souboru
serveru. Cursor spouští procesy MCP v kontextech, kde pracovní adresář nemusí být
co očekáváte.
7. Zabezpečení a správa přihlašovacích údajů MCP
Bezpečnost je pravděpodobně nejkritičtějším aspektem implementace MCP v profesionálním kontextu. Servery MCP mají přístup k citlivým zdrojům (databáze, API, souborový systém) a chybnou konfiguraci může odhalit kritická data.
7.1 Princip nejmenšího privilegia
Základním principem je konfigurace každého serveru MCP s minimálními nezbytnými oprávněními:
// 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 Bezpečné řízení proměnných prostředí
// 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: Zabezpečení MCPoison a mcp.json
V roce 2025 byla zdokumentována zranitelnost nazvaná „MCPoison“ (CVE-2025-54136) ovlivňující Cursor:
Jakmile uživatel schválí server MCP, kurzor přiřadí důvěryhodnost serveru jméno
serveru, nikoli příkaz. Soubor mcp.json upraveno útočníkem v
sdílené úložiště by mohlo nahradit provedený příkaz při zachování stejného důvěryhodného názvu.
Opatření ke zmírnění MCPoison
- Nezavazujte se
.cursor/mcp.jsons přihlašovacími údaji ve sdílených úložištích - Přidat
.cursor/mcp.jsonal.gitignorepokud obsahuje pověření - Použít globální konfiguraci (
~/.cursor/mcp.json) pro vaše osobní přihlašovací údaje - Pravidelně aktualizujte kurzor: novější verze zlepšují správu důvěryhodnosti
- Vždy zkontrolujte obsah
mcp.jsonpo stažení ze sdílených úložišť
# .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. Odstraňování problémů s připojením MCP
MCP je relativně mladá technologie a problémy s připojením jsou běžné, zejména během počáteční konfiguraci. Zde je systematický průvodce diagnostikou a řešením nejčastějších problémů.
8.1 Zkontrolujte stav serverů
Prvním krokem je vždy zkontrolovat stav serverů z uživatelského rozhraní kurzoru:
- OTEVŘENO Nastavení (Cmd/Ctrl + ,)
- Přejděte do sekce MCP v bočním panelu
- Každý server zobrazuje indikátor: zelená (připojeno), žlutá (připojování), červená (chyba)
- Klepnutím na ikonu protokolu vedle serveru, který selhal, zobrazíte chybové zprávy
8.2 Běžné problémy a řešení
// 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 Povolit ladění 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 vs tradiční přístupy
Pro pochopení skutečné hodnoty MCP je užitečné jej porovnat s tradičními integračními přístupy mezi AI a externími nástroji:
| čekám | Tradiční přístup | MCP |
|---|---|---|
| Integrace | Ručně zkopírujte a vložte schéma/data do chatu | Přímý a strukturovaný přístup v reálném čase |
| Standardizace | Každé IDE má nekompatibilní proprietární pluginy | Jeden server pracuje se všemi klienty MCP |
| Bezpečnost | Pověření ve výzvách nebo v kontextu chatu | Pověření v procesu serveru, nikdy vystavené modelu |
| Složitelnost | Izolované integrace, obtížně kombinovatelné | V jednom pracovním postupu lze kombinovat více serverů |
| Údržba | Jakákoli vlastní integrace, která se má udržovat | Udržovaný ekosystém komunitních serverů |
| Aktualizace dat | Statická data v (statickém) kontextu | Živý přístup k aktualizovaným datům |
10. Praktický pracovní postup: MCP s úhlovým projektem
Podívejme se, jak MCP transformuje vývojový pracovní postup na projektu Angular s backendem PostgreSQL, kombinace více serverů do jedné provozní konfigurace:
// .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"
}
}
}
}S touto aktivní konfigurací budou výzvy, které můžete v kurzoru používat, mnohem výkonnější:
Pokročilé výzvy s MCP Multi-Server
- "Podívejte se na problém #142 na GitHubu a implementujte požadovanou funkci. Schéma databáze je in postgres/my_db, zahrnutá tabulka se nazývá předplatné."
- "Napište testy E2E pro komponentu UserList. Ke generování použijte skutečné schéma databáze." realistická testovací data."
- "V commit abc1234 došlo k regresi. Porovnejte aktuální schéma s tímto předchozí a identifikujte změny, které mohly způsobit problém."
- "Vygenerujte soubor migrace TypeORM a přidejte potřebné sloupce do tabulky uživatelů, na základě aktuální struktury databáze."
11. Nejlepší postupy pro MCP ve výrobě
Kontrolní seznam MCP pro vývojové týmy
- Oddělení místností: používat různé MCP servery pro vývoj, přípravu a produkci, nikdy stejný server MCP neukazuje na více prostředí
- Ve výchozím nastavení pouze pro čtení: nakonfiguruje všechny databázové servery jako pouze pro čtení; umožňuje zápis pouze na dedikované servery a s dvojím potvrzením
- Otočení klíče: nastavit expiraci na tokenech API používaných servery MCP; 60-90 dní je dobrá praxe
-
Gitignore pro mcp.json: nikdy neverzované soubory s přihlašovacími údaji; USA
mcp.json.examplejako sdílená šablona - Sledování: implementovat strukturované protokolování na vlastních serverech pro sledování které nástroje jsou vyvolány a ze které relace kurzoru
- Časové limity: přidejte časové limity volání API na serveru, abyste tomu zabránili Kurzor čeká nekonečně dlouho
- Ověření vstupu: použijte Zod nebo podobný k ověření přijatých parametrů z nástrojů před prováděním operací
// 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);
}
});Závěry
Protokol kontextu modelu představuje kvalitativní skok v interakci s AI IDE rozvojovou infrastrukturu. Místo toho, abyste pracovali izolovaně se statickými, obecnými informacemi, Kurzor s nakonfigurovaným MCP se stává agentem schopným uvažovat o vašem skutečném kontextu: schématu aktuální stav vaší databáze, otevřené problémy na GitHubu, konkrétní konfigurace vašeho projektu.
Viděli jsme, jak konfigurovat MCP globálně i na úrovni projektu, jak používat předpřipravené servery pro nejběžnější případy použití (PostgreSQL, GitHub, souborový systém), jak vytvořit vlastní servery v TypeScript integrovat proprietární systémy a jak řídit zabezpečení a řešení problémů profesionálním způsobem.
Přirozeným dalším krokem je zkombinovat MCP s dalšími pokročilými funkcemi Cursoru: používat MCP v režimu agenta, aby agent prováděl vícekrokové operace, které vyžadují přístup k databáze a úložiště; použijte režim plánu k plánování složitých prvků zahrnujících vzor migrace a kód aplikace dohromady. Možnosti se ohromně množí.
Ekosystém MCP rychle roste: každý týden jsou publikovány nové servery na npm a na oficiálním antropickém úložišti. Vyplatí se pravidelně procházet katalog, abyste to zjistili nové integrace, které mohou urychlit váš pracovní postup.
Související články v této sérii
- 01 - Cursor IDE: Kompletní průvodce pro vývojáře
- 02 – Pravidla kurzoru: Konfigurace AI pro váš projekt
- 03 - Režim agenta: Upravte kódovou základnu pomocí příkazu
- 04 - Režim plánu a agenti na pozadí
- 05 - Kurzorové háky: Automatizujte pracovní postup
- 07 - Ladění pomocí kurzoru AI: 3x rychlejší
- 08 - Cursor vs Windsurf vs Copilot v roce 2026
- 09 - Profesionální pracovní postup: Úhlový projekt s kurzorem
Související série
- Řada MCP (ID 64–77): dokončit hloubkovou studii o Protokolu kontextu modelu, Pokročilá architektura a implementace pro všechny klienty MCP
- Moderní Angular (ID 224–233): profesionální Angular workflow můžete vylepšit pomocí integrací MCP uvedených v tomto článku
- Vibe Coding (ID 281-288): AI-first přístup k vývoji, perfektně doplněk k pokročilému použití kurzoru s MCP