# VC-078 · MCP bağlantısının gizli anahtarı paylaşılan ayar dosyasında düz metin duruyor

MCP bağlantısı için kullanılan anahtarın değeri proje ayarına yazılıyor. Dosya paylaşılınca veya ajanın başka bir aracı tarafından okununca bağlantı yetkisi de dosyayla birlikte taşınabiliyor.

- Önem: YÜKSEK. Etkisi büyük. Kodlama ajanı üzerinden tetiklenir ve bulmak için kaynak kodu görmek gerekir.
- Önem notu: Paylaşılan veya ajanın okuyabildiği MCP ayarında çalışan özel servis tokenı bulunduğu varsayılır. Anahtarın kapsamı ve ömrü etkiyi değiştirir. Ortam değişkenine başvuru, tokenın bütün yerel süreçlerden gizlendiği anlamına gelmez.
- Eksen ve kategori: Güvenlik, 11 Ajan ve geliştirme ortamı
- Yığın: Claude Code, Cursor, Node.js, Her yığın
- Yapay zekâ kodunda: ölçülmedi. Dayanak: uzman görüşü.
- Ne zaman bakılır: Kodlama ajanını kurarken, Her ay
- CWE: CWE-312
- OWASP Top 10:2025: A06:2025 Insecure Design
- Checklist ifadesi: MCP bağlantılarının gizli anahtarları paylaşılan ayar dosyasında düz metin durmuyor.
- Son inceleme: 4 Ekim 2026, Komünite editörlüğü
- Adres: https://vibecheck.komunite.com.tr/madde/mcp-ayar-dosyasinda-duz-metin-sir-var

## 60 saniyelik kontrol

Yalnız kendi uygulamanda ya da yazılı izin aldığın sistemde dene. Bu bir sızma testi değildir.

1. MCP ayarındaki env, headers, args ve URL alanlarını değerleri günlüğe basmadan incele.
2. Anahtarın kendisiyle ortam değişkenine başvuruyu ayır, yalnız alan adına göre karar verme.
3. Paylaşılan yapılandırmayı yerel yapay tokenla üretip token değerinin dosyaya girmediğini kontrol et.
4. Gerekli değişken eksikken başlatma kontrolünün güvenli biçimde durduğunu doğrula.
5. Eski gerçek tokenın Git geçmişine veya paylaşılan kayda girip girmediğini ayrıca değerlendir.

## Ne oluyor

MCP sunucusunu bağlamak için verilen örnekte bir Authorization alanı var. Kendi tokenını buraya yapıştırıyorsun ve bağlantı çalışıyor. Ardından ayarı projeyle paylaşıyor, hata ayıklamak için sohbete koyuyor veya başka makineye taşıyorsun. Artık dosyayı alan kişi yalnız bağlantının nasıl kurulacağını öğrenmiyor, tokenın verdiği yetkiyi de alabiliyor.

Alan adının `env` olması bu sorunu kendiliğinden çözmez. Yapılandırma dosyasındaki ortam değişkeni değerine anahtarın kendisini yazmak da düz metin saklamadır. Çalışma anında dışarıdan sağlanan bir değere başvurmak farklıdır. Ayrım, dosyada özel değerin bulunup bulunmadığı ve o dosyanın kimler tarafından okunabildiğidir.

MCP ortamında bu ayrım özellikle görünür olur. Ajan bir bağlantı sorununu çözmek için ayar dosyasını okuyabilir veya başka araç bu dosyaya ulaşabilir. Gizli anahtarı genel yapılandırmadan ayırmak bu veri yolunu daraltır. Ancak anahtarı ortam değişkenine taşımak onu bütün süreçlerden gizleyen bir kasa kurmaz. Çalışma anındaki erişim ve sunucuya verilen yetki ayrıca sınırlandırılmalıdır.

## Gerçek olay

Bu maddede belirli bir kullanıcıya ait düz metin MCP anahtarı sızıntısı olay olarak sunulmuyor. [Claude Code MCP belgesi](https://code.claude.com/docs/en/mcp), paylaşılan `.mcp.json` dosyalarında ortam değişkeni başvurusunu destekler. Başvuru çözümlenmesi istemci davranışıdır. Her MCP istemcisinin aynı sözdizimini desteklediği varsayılmaz.

[OWASP sır yönetimi rehberi](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html), sırların erişimini ve yaşam döngüsünü birlikte ele alır. [CWE-312](https://cwe.mitre.org/data/definitions/312.html), başka erişim alanına açık kaynakta hassas bilginin düz metin saklanmasını sınıflandırır. Yerel örnekte yapay tokenla paylaşılan yapılandırma üretilir. Hatalı sürüm değeri dosyaya koyar, iyi sürüm yalnız değişken adını taşır. Gerçek sunucuya bağlanılmaz, gerçek token okunmaz ve kimlik doğrulamanın çalıştığı iddia edilmez.

## Yapay zekâ bunu neden üretiyor

**Çalışan örnek doğrudan kaydedilir.** Ajan bağlantıyı kurmak için aldığı anahtarı örnek yapılandırmanın içine yerleştirebilir. İlk hedef sunucudan yanıt almaktır. Dosyanın sonra kimlerle paylaşılacağı ve ajanın bağlamına girip girmeyeceği düşünülmeyebilir. Çalışan bağlantı, sırrın doğru yerde saklandığını göstermez. Bağlantı kurulumu ve paylaşılabilir yapılandırma ayrı ihtiyaçlardır.

**Yerel dosya gizli kabul edilir.** Ayar kullanıcı makinesinde durduğu için erişim kapsamı sorgulanmayabilir. Fakat dosya yedeğe, hata raporuna, sohbet bağlamına veya depoya taşınabilir. Ajan dosyanın o anki konumunu görürken bu sonraki kullanımları bilmeyebilir. Bu nedenle paylaşılacak çıktının sır içermemesi ayrıca doğrulanmalıdır.

**Env sözcüğü güvenli saklama sanılır.** Yapılandırmanın `env` alanına yazılan değer ile dış ortamdan çözülen başvuru karıştırılabilir. Birincisinde anahtar hâlâ dosyadadır. İkincisinde ise dosya yalnız hangi değere ihtiyaç duyduğunu belirtir. Üretilen JSON'u yapay işaretle denetlemek bu farkı metin tartışmasından çıkarıp somut hale getirir.

**Eksik değişken sessiz geçilir.** Ajan anahtarı başvuruya dönüştürünce işin bittiğini sanabilir. İstemci değişken yokken boş veya çözümlenmemiş değerle devam edebilir. Bağlantının beklenen kimlikle açıldığını ayrıca kontrol etmek gerekir. Bu açıklamalar olası üretim mekanizmalarıdır. AI ile üretilen MCP ayarlarında hata sıklığını gösteren bir ölçüm olarak sunulmaz.

## Etki

Dosyayı okuyabilen başka bir aktör tokenın yetkileriyle servise erişebilir. Etki yalnız anahtarın görünür olmasına değil, kapsamına ve geçerlilik süresine bağlıdır. Dar bir test anahtarıyla bütün hesabı yöneten kalıcı token aynı zarar potansiyelini taşımaz. Ayar dosyasının özel kalması da tek koruma olmamalıdır.

Gerçek anahtar daha önce paylaşılmışsa alanı silmek geçmiş kopyaları geri almaz. Git geçmişi, sohbet kayıtları veya yedekler eski değeri tutabilir. Anahtarı değiştirmek ve eski yetkiyi kapatmak gerekir. Yerel örnekte kullanılan değerler yapaydır. Testin başarısı geçmişte gerçek bir sırrın hiç paylaşılmadığını veya bütün kopyaların temizlendiğini kanıtlamaz.

## Nasıl anlarsın

MCP ayarında header, URL, komut argümanı ve `env` değerlerini incele. Değerleri rapora basma. Literal sır, ortam değişkeni başvurusu ve açık sunucu kimliği arasında ayrım yap. Yalnız token sözcüğünü aramak bazı sırları kaçırır, bazı açık tanımları yanlış işaretler. Dosyanın kullanımını ve erişim alanını da belirle.

Yerel testte ayar üreticisine yapay token ver. Çıktıda bu değer bulunmamalı, beklenen değişken başvurusu korunmalı. Anahtar eksik, boş veya yanlış türde olduğunda başlatma öncesi kontrol açık hata vermeli. Hata mesajı değeri tekrar etmemeli. Normal sunucu adresi ve bağlantı türü aynı kalmalı. Bu test bağlantı kurulmasını gerektirmez.

## Nasıl düzeltirsin

1. **Paylaşılan dosyayı ayır.** Proje yapılandırmasında yalnız bağlantı tanımı ve sır başvurusu tut. Örnek Claude Code için belgelenmiş değişken sözdizimini üretir. Başka istemcide onun desteklediği yöntemi doğrula. Anahtarı aynı depodaki ikinci bir dosyaya taşımak paylaşım sorununu çözmez.
2. **Çalışma değerini ayrıca sağla.** Sır yöneticisi veya erişimi sınırlandırılmış çalışma ortamı kullan. Tokenı yalnız gereken sürece ve sunucuya ver. Örnekte ortam değeri argüman olarak sağlanır, gerçek sır deposu kurulmaz. Başvurunun çözülmüş halini günlüğe basma.
3. **Eksik değeri durdur.** Örnek yapılandırma üretilmeden önce gereken değişkeni kontrol eder. Claude Code belgesinde eksik değişkenin bazı alanlarda çözümlenmemiş bırakılabildiği anlatılır. Bu nedenle eksik değerin kendiliğinden güvenli hata yaratacağına dayanma. Kendi başlatma kontrolünü açık yap.
4. **Geçmiş ifşayı gider.** Gerçek tokenın paylaşılmış olduğunu doğrularsan onu değiştir ve eski yetkiyi kaldır. Yeni tokenı görev için daralt. Geçmiş dosya temizliği ayrı işlemdir ve token iptalinin yerine geçmez. Yalnız yapay örnek değerler için servis değişikliği yapman gerekmez.

## Bir daha olmasın

MCP yapılandırma değişikliğinde paylaşılan çıktıyı yapay sırla test et. Bağlantı hatası raporlarında değer yerine değişken adını göster.

## Sınır

Bu madde paylaşılan veya erişimi geniş MCP ayarında düz metin sır saklanmasını kapsar. Anahtarın ajana gereğinden geniş yetki vermesi ve araç açıklamasıyla yönlendirme ayrı konulardır. Ortam değişkeni başvurusu şifreleme veya süreç yalıtımı değildir. OAuth kullanan bağlantının token saklama davranışı kendi istemcisi üzerinden ayrıca değerlendirilir.

## Düzeltme kodları

### Node.js: Paylaşılan ayarda sır başvurusu

Önce:

```js
// mcp/paylasilan-ayar.js, açıklama amaçlı. env yalnız test veya güvenilir başlatıcıdan gelir.
export function sharedConfig(env) {
  const token = env.CATALOG_MCP_TOKEN;
  if (typeof token !== 'string' || !token.trim()) throw new Error('CATALOG_MCP_TOKEN gerekli');
  return {
    mcpServers: {
      catalog: {
        type: 'http',
        url: 'https://catalog.example.invalid/mcp',
        // Bu nesne dosyaya yazıldığında anahtar da paylaşılır.
        headers: { Authorization: `Bearer ${token}` },
      },
    },
  };
}
```

Sonra:

```js
// mcp/paylasilan-ayar.js, açıklama amaçlı. Claude Code .mcp.json çıktısı üretir.
export function sharedConfig(env) {
  const token = env.CATALOG_MCP_TOKEN;
  if (typeof token !== 'string' || !token.trim()) throw new Error('CATALOG_MCP_TOKEN gerekli');
  // Aynı değişken Claude Code çalışma ortamına ayrıca sağlanmalıdır.
  return {
    mcpServers: {
      catalog: {
        type: 'http',
        url: 'https://catalog.example.invalid/mcp',
        // Tek tırnak başvuruyu burada çözmeden saklar.
        headers: { Authorization: 'Bearer ${CATALOG_MCP_TOKEN}' },
      },
    },
  };
}
```

Düzeltmeyi kanıtlayan test:

```js
// mcp/paylasilan-ayar.test.mjs, açıklama amaçlı. Gerçek ortam veya ağ okunmaz.
import test from 'node:test';
import assert from 'node:assert/strict';
const { sharedConfig } = await import(process.env.ORNEK_DOSYA);
test('paylaşılan çıktı sır değeri yerine başvuru içerir', () => {
  const marker = 'YAPAY_TOKEN_78';
  const config = sharedConfig({ CATALOG_MCP_TOKEN: marker });
  const serialized = JSON.stringify(config);
  assert.equal(serialized.includes(marker), false);
  const server = config.mcpServers.catalog;
  assert.equal(server.headers.Authorization, 'Bearer ${CATALOG_MCP_TOKEN}');
  assert.equal(server.type, 'http');
  assert.equal(server.url, 'https://catalog.example.invalid/mcp');
  for (const value of [undefined, '', '  ', 42]) {
    assert.throws(() => sharedConfig({ CATALOG_MCP_TOKEN: value }), /CATALOG_MCP_TOKEN gerekli/);
  }
});
```

## Ajan kuralı (AGENTS.md)

```md
## MCP ayarında düz metin anahtar (vibecheck VC-078)
- Paylaşılan MCP yapılandırmasına çalışan token değeri yazılmaz.
- İstemcinin desteklediği sır veya ortam değişkeni başvurusu kullanılır.
- Gerekli sır eksikse bağlantı kurulmadan açık hata verilir.
- Token yalnız gereken sunucu ve görev kapsamına verilir.
- Yapılandırma çıktıları ve hata kayıtları sır değeri taşımaz.
- Daha önce paylaşılmış anahtar yalnız dosyadan silinmez, ayrıca değiştirilir.
```

## Kaynaklar

1. [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp), Anthropic
2. [Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html), OWASP
3. [CWE-312 Cleartext Storage of Sensitive Information](https://cwe.mitre.org/data/definitions/312.html), MITRE

---

vibecheck · Komünite editörlüğü. Metin CC BY 4.0, prompt ve kural parçaları MIT-0. Kaynak: https://vibecheck.komunite.com.tr/madde/mcp-ayar-dosyasinda-duz-metin-sir-var