# MCP ile bağlanın

Claude Desktop, Claude Code, Cursor, Codex ya da başka bir MCP istemcisini Oleafly'nin yerel proje araçlarına bağlayın.

Oleafly, bir MCP (Model Context Protocol) sunucusu olarak çalışabilir. Claude Desktop, Claude Code, Cursor, Codex ve Grok CLI gibi MCP istemcileri bir Oleafly projesini okuyabilir, düzenleyebilir, arayabilir ve derleyebilir. Modeli istemci sağladığı için Oleafly'de bir yapay zeka sağlayıcı anahtarına ihtiyacınız yoktur.

Elinizde zaten bir Claude (ya da benzeri) aboneliği varsa ve o sohbet uygulamasının [Ayarlar](/docs/ai-setup/) içine bir API anahtarı yapıştırmadan Oleafly'yi yönetmesini istiyorsanız, aradığınız seçenek budur.

## Etkinleştirme

1. **Ayarlar → Tümleştirmeler → Oleafly MCP** bölümünü açın.
2. **MCP sunucusunu aç** düğmesini açık konuma getirin.

Sunucu yalnızca Oleafly süreci açıkken çalışır. Yalnızca `127.0.0.1` adresinde dinler, yerel ağınızda asla dinlemez. Proje penceresini kapatmak sunucuyu durdurmaz; durduran, MCP'yi kapatmak ya da Oleafly'den çıkmaktır.

Oleafly `5323` bağlantı noktasını yeğler (`http://127.0.0.1:5323/mcp`). Bu nokta kullanılamıyorsa sunucu otomatik olarak başka bir boş yerel bağlantı noktasına bağlanır ve bunu sonraki açılış için kaydeder. Ayarlar, etkin URL'yi gösterir. Onun yeniden başlat düğmesi mümkünse geçerli bağlantı noktasını yeniden kullanır ya da başka bir boş nokta seçer.

## İstemcinizi bağlayın

:::tip[Kopyalanacak belirteç yok]
`oleafly` komutunun, standart girdi ve çıktı üzerinden konuşan kendi MCP sunucusu vardır. Çalışan uygulamayı ve belirtecini kendisi bulur; bu yüzden bir URL ya da belirteç kopyalamazsınız ve Node.js'e ihtiyacınız yoktur. `oleafly mcp config --client claude-desktop` kurulumu yazdırır; istemci adları `claude-code`, `claude-desktop`, `codex`, `cursor` ve `gemini`'dir. Bkz. [Komut satırı aracı](/docs/cli/#connect-an-agent-over-mcp).
:::

Ayarlar, yaygın istemciler için kopyala-yapıştır parçacıkları gösterir. Seçilen bağlantı noktası `5323`'ten farklı olabileceğinden canlı URL'yi kopyalayın, ardından `<token>` değerini Ayarlar'daki taşıyıcı belirteçle değiştirin (Göster / Kopyala).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

`claude_desktop_config.json` dosyasına ekleyin (Desktop stdio'yu yeğlediğinden `mcp-remote` üzerinden stdio köprüsü):

```json
{
  "mcpServers": {
    "oleafly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:5323/mcp",
        "--header",
        "Authorization: Bearer <token>",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

### Claude Desktop uzantısı

Her sürüm, bir Claude Desktop uzantısı olan `oleafly.mcpb` dosyasını içerir; bu yüzden yapılandırma dosyasına ve tokena ihtiyacınız olmaz. Dosyayı [son sürümden](https://github.com/Oleafly/Oleafly/releases/latest) indirin ve kurmak için Claude Desktop ile açın.

Uzantı, uygulamayla gelen `oleafly` komutunu başlatır ve Oleafly'de açık olan proje üzerinde çalışır; bu yüzden Oleafly'yi MCP sunucusu açık şekilde çalışır durumda tutun. Claude Desktop komutu bulamazsa uzantının ayarlarından seçin: macOS'ta `Oleafly.app/Contents/MacOS` içindeki `oleafly-cli`, Windows'ta `%LOCALAPPDATA%\Oleafly` içindeki `oleafly-cli.exe`.

MCP Registry aynı uzantıyı `io.github.Oleafly/oleafly` adıyla listeler.

### Cursor / VS Code

`.cursor/mcp.json` dosyasına (ya da istemcinizin MCP yapılandırmasına) ekleyin:

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

`~/.grok/config.toml` içinde:

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

Oleafly ayarlarındaki **Codex CLI** parçacığını kullanın; bu parçacık çalışan sunucuya bir stdio köprüsü sağlar. Girdiyi Codex yapılandırmanıza ekleyin ve Oleafly'nin gösterdiği canlı URL ile belirteci kullanın:

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://127.0.0.1:5323/mcp",
  "--header",
  "Authorization: Bearer <token>",
  "--transport",
  "http-only"
]
```

Köprü, Node.js ve `npx` gerektirir. Yapılandırmayı değiştirdikten sonra istemciyi yeniden başlatın ya da yeniden bağlayın.

Kurulumu betikle yapmak isterseniz, Oleafly verilerinizin yanındaki (Ayarlar'da gösterilen) `mcp.json` dosyası aynı URL'yi ve belirteci tutar. Yalnızca sunucu çalışırken yazılır (Unix'te `0600` kipi) ve sunucu durduğunda silinir. Ona, diğer yerel gizli bilgiler gibi davranın.

## Araçlar neler yapabilir

MCP araçlarının çoğu adlarını ve şemalarını uygulama içi asistanla paylaşır. Proje keşfi ve yönlendirme araçları masaüstü arka ucu tarafından sağlanır.

Açık bir proje varken araçlar, uygulamada açık olan projeyi hedefler. Bağlı bir pencereyle başka bir projeyi seçmek için `list_projects` ve `open_project` kullanın.

Son pencere kapandıktan sonra arka uç `read_file`, `list_files` ve `search_project` araçlarını kullanıma açık tutar. Onay ilkesi izin verdiğinde yerel yazmalar, değiştirmeler, oluşturmalar ve yeniden adlandırmalar da kullanılabilir kalır. Bu araçlar yalnızca uygulamanın bildirdiği son projeyi kullanır ve o proje artık geçerli değilse çağrıyı reddeder. Kitaplıktaki diğer projelerden asla tahmin yürütmezler. Durum, proje seçimi, silme, derleme, günlükler, PDF incelemesi, tema değişiklikleri ve şekil araçları bağlı bir pencere gerektirir.

### Yön bulma

| Araç | Ne yapar |
|---|---|
| `get_status` | Oleafly sürümü, açık proje, belge motoru, ana belge, son derleme durumu ve son derlemenin neden başarısız olduğu ya da çalışamadığı |
| `list_projects` | Kimlikleri, adları, motorları, türleri, ana belgeleri, zaman damgaları, renkleri, önizleme durumu ve dışa aktarma geçmişiyle projeler |
| `open_project` | Bir projeyi kimliğiyle açar; böylece diğer araçlar onu hedefler |
| `list_files` | Proje dosya ağacı |
| `project_map` | Ana hatlar, etiketler, atıflar, makrolar, giriş grafiği, çözülmemiş başvurular |
| `search_project` | Geçerli projede metin arar |

### Okuma

| Araç | Ne yapar |
|---|---|
| `read_file` | Bir proje dosyasını okur |
| `get_log` | Son derleme günlüğü |
| `get_pdf_text` | Derlenen PDF'den çıkarılan metin |
| `verify_pdf_pages` | Oluşturulan PDF sayfalarını yerleşim sorunları için sayfa görüntülerinden ya da sayfa metninden denetler |

`get_pdf_text` ve `verify_pdf_pages`, Oleafly'nin elindeki son PDF'i okur. Son derleme başarısız olduğunda ya da çalışamadığında sonuçları PDF'in eski olduğunu ve nedenini söyler; çünkü PDF daha önceki bir derlemeden gelir ya da başarısız derlemeden kalan kısmi bir PDF'dir. `get_log` da son derleme çalışamadığında aynısını söyler, çünkü günlük o zaman daha önceki bir derlemeden gelir.

### Düzenleme

| Araç | Ne yapar |
|---|---|
| `write_file` | Bir dosyaya yazar ya da üzerine yazar |
| `replace_in_file` | Bir dosya içinde bulur ve değiştirir |
| `create_file` | Bir dosya veya klasör oluşturur |
| `rename_file` | Bir yolu yeniden adlandırır ya da taşır |
| `delete_file` | Bir dosya veya klasörü siler |
| `set_main_doc` | Derleme giriş belgesini ayarlar |

### Derleme ve şekiller

| Araç | Ne yapar |
|---|---|
| `compile` | Projeyi PDF'e derler |
| `preview_figure` | Bir şekli tek başına işler ve bir PNG görüntüsü döndürür |
| `insert_figure` | Son önizlenen şekli belgeye ekler |
| `load_image` | Şekil çalışması için projeden bir görüntü yükler |

`compile`, derlemenin işe yarayıp yaramadığını söyler, hatalarını listeler, bir PDF olup olmadığını belirtir ve günlüğün son bölümüyle biter. Biten bir derleme uyarılarını da bildirir. Derleme çalışamadığında, bitmediğinde ya da bir TeX kurulumu ya da bulunmayan bir Typst sürümü gibi kaynağın dışında bir şeye ihtiyaç duyduğunda sonuç nedeni verir ve Oleafly'nin uygulamada size sunduğu çözümü adlandırır. Araç, istemciden size söylemesini ve kaynağınıza dokunmamasını ister. Durdurduğunuz bir derleme durduruldu olarak işaretlenir; böylece istemci onu koddaki bir hata saymaz. Oleafly'nin kendi asistanı aynı sonucu alır.

Projenin LaTeX, Typst yoksa Markdown olduğunu öğrenmek için önce `get_status` çağırın, sonra kaynağı o biçimde yazın. `preview_figure` ve `insert_figure`, LaTeX ve Typst projelerinde çalışır:

- LaTeX'te şekil, küçük bir bağımsız belgede derlenen TikZ kodudur ve `insert_figure` onu bir `figure` ortamına sarar.
- Typst'te şekil, projenin Typst sürümüyle işlenen Typst işaretlemesidir; örneğin bir CeTZ tuvali ya da bir fletcher diyagramı. `insert_figure` onu `#figure` içine sarar, etiketi ondan sonraya koyar ve `#import` satırlarını onun üstüne taşır.
- Markdown projesinde her iki araç da hata döndürür ve hiçbir şeyi değiştirmez.

`load_image` her projede çalışır.

### Uygulama

| Araç | Ne yapar |
|---|---|
| `toggle_theme` | Açık / koyu kipi değiştirir |

### Beceriler

| Araç | Ne yapar |
|---|---|
| `list_skills` | Kurulu becerileri kimlikleri, adları, açıklamaları ve açık olup olmadıklarıyla listeler |
| `load_skill` | Bir becerinin tam yönergelerini ve dosya listesini yükler |
| `read_skill_file` | Bir becerinin klasöründen bir başvuru ya da betik okur |

Beceri araçları, açık proje ve Oleafly penceresi olmadan, bağlantı kurulur kurulmaz çalışır. Bir istemci, Ayarlar'da kapatılmış olanlar dahil her geçerli beceriyi görür: anahtarlar, Oleafly'nin kendi asistanının hangi becerileri kullanacağını belirler; bir istemcinin neleri okuyabileceğini değil. Becerileri bunun yerine bir klasörden okuyan ajanlar, **Ayarlar → Yapay Zeka Asistanı → Beceriler** içindeki **Becerileri bu bilgisayardaki diğer ajanlarla paylaş** seçeneğini kullanabilir. [Beceriler](/docs/skills/) sayfasına bakın.

### Notlar

Bu araçlar, [Notlar'ı açın](/docs/notes/#turn-on-notes) bölümünde anlatıldığı gibi **Ayarlar → Deneysel Özellikler** bölümünde **Notlar** açıkken bulunur. Açık proje üzerinde değil, notlarınız üzerinde çalışırlar ve bağlı bir pencere gerektirirler.

| Araç | Ne yapar |
|---|---|
| `list_knowledge_notes` | Notlarınızı, en yenisi önce, kimlikleri, başlıkları, etiketleri, bağlı projeleri ve kısa özetleriyle listeler. Etikete ya da projeye göre filtreler |
| `search_notes` | Notlarınızda arar ve kimlikleri, başlıkları, etiketleri, bağlantıları ve eşleşen parçaları döndürür |
| `read_note_by_id` | Bir notu ön bilgisiyle birlikte Markdown olarak okur |
| `today_note` | Bugünün günlük notunu ya da henüz yoksa sahip olacağı başlığı okur |
| `list_note_tasks` | Notlarınızdaki onay kutulu görevleri, en yeni not önce, listeler. Nota göre ve açık ya da tamamlanmış olmasına göre filtreler |
| `note_backlinks` | Bir nota bağlantı veren notları, her bağlantının çevresindeki metinle listeler |
| `append_to_note` | Bir notun ya da bugünün günlük notunun sonuna Markdown ekler |
| `edit_note_section` | Bir notun tek bir başlığın altındaki bölümünü yeniden yazar ya da sonuna ekleme yapar |
| `create_note` | Başlığı, Markdown'ı, etiketleri ve bağlı bir projesi olan bir not oluşturur |

`append_to_note` ve `edit_note_section` nota yazmaz. Değişiklikleri, siz Oleafly'de kabul edene kadar notta öneri olarak görünür. `create_note` Oleafly'de onayınızı bekler; `append_to_note` da önce bugünün günlük notunu oluşturması gerektiğinde öyle. **Bu bağlantıya güven** altında not oluşturmak sormaz. Bir iş birliği sunucusu üzerinden paylaşılan bir not bu yolla okunabilir ama değiştirilemez. **Salt okunur**, notları değiştiren üç aracı kaldırır.

## Onaylar ve güvenlik

Birçok MCP istemcisi bir aracı çağırmadan önce sorar. Oleafly ayrıca **Ayarlar → Tümleştirmeler → Oleafly MCP** içinde seçilen ilkeyi uygular:

- **Her değişikliği onayla** varsayılandır. Yazma, yeniden adlandırma ve silme işlemleri, bir uygulama penceresi bağlıyken bir onay kartı gösterir. Pencere yokken bu işlemler reddedilir, çünkü kartın gösterileceği bir yer yoktur.
- **Düzenlemeleri otomatik onayla, silmeleri sor**, yazma ve yeniden adlandırma işlemlerinin arka uçta çalışmasına izin verir. Silmeler onay için yine bağlı bir pencere gerektirir.
- **Bu bağlantıya güven**, arka uç yazmalarının ve yeniden adlandırmalarının Oleafly istemi olmadan çalışmasına izin verir. Silme yine bağlı bir pencere gerektirir. Bu ilkeyi yalnızca istemciye ve onun kendi onay denetimlerine güveniyorsanız kullanın.

Bunu destekleyen iki anahtar daha vardır:

- **Salt okunur** (ayrı bir anahtar), değiştiren araçları `tools/list` listesinden tamamen kaldırır; böylece dış bir uygulama, yukarıdaki ilke ne olursa olsun dosyaları okuyabilir ve derleyebilir ama asla değiştiremez.
- **Taşıyıcı belirteç**: `~/.oleafly/` altındaki kimlik doğrulamalı şifreli yerel depoda tutulan 256 bitlik rastgele bir değer. Eski istemcileri geçersiz kılmak için onu yeniden üretin. Genel yapılandırma okumaları belirteci asla açığa çıkarmaz. Onu Ayarlar içinde yalnızca çalışan sunucunun bağlantı denetimleri gösterebilir.

Ve yapılandırmadığınız iki değişmez daha vardır:

- **Yalnızca localhost**: bağlanma adresi `127.0.0.1`'dir. Tarayıcı `Origin` başlığı taşıyan istekler reddedilir ve `Host` geri döngü olmalıdır.
- **Proje kısıtı**: arka uç dosya araçları projeye göreli yolları kabul eder ve standart yolları uygulamanın bildirdiği projeyle sınırlar. Bir araç çağrısı başka bir proje kimliği veremez ya da arka ucun kitaplıktan başka bir projeyi seçmesini sağlayamaz.

## Çalışmasını izleyin

Bir pencere bağlıyken **MCP etkinliği** sekmesi gelen çağrıları günlüğe kaydeder. Son pencere kapandıktan sonra arka uç çağrıları sürebilir, ama bir pencere yeniden bağlanana kadar bir etkinlik paneli ya da onay kartı yoktur.

## Tarayıcıdaki claude.ai neden bağlanamıyor

Bir bulut sohbet hizmeti, makinenizdeki `127.0.0.1` adresine ulaşamaz. Onun yerine **Claude Desktop** (ya da Claude Code, Cursor vb.) kullanın. MCP bağlantı noktasını genel internete tünellemeyin: bu, elinde URL olan herkesin yerel proje dosyalarınızı düzenlemesine ve silmesine yol açar.

## Sorun giderme

| Belirti | Denenecekler |
|---|---|
| Bazı araçlar kullanılamıyor | Şekil önizlemeleri ve diğer yalnızca arayüz araçları bir Oleafly penceresi gerektirir. Uygulamayı ve projeyi açın, sonra `tools/list` çağrısını yeniden deneyin. |
| Bağlantı noktası `5323`'ten değişti | Yeğlenen nokta kullanılamıyordu; Oleafly boş bir nokta seçti. Ayarlar'dan canlı URL'yi kopyalayın. |
| HTTP 401 | Belirteç uyuşmazlığı (örneğin Yeniden üret sonrasında). Yeni belirteci istemciye kopyalayın. |
| HTTP 403 | İstemci bir `Origin` başlığı ya da geri döngü olmayan bir `Host` gönderdi. Bir tarayıcı sekmesi değil, yerel bir MCP istemcisi kullanın. |
| Çağrı zaman aşımına uğradı | Her araç çağrısı, derlemeler için ya da Onayla'yı tıklamanız için en çok **5 dakika** (300 sn) bekler. Bekleyen kartları onaylayın ya da reddedin, ya da yeniden deneyin. Bir derleme daha uzun sürebilir; bir Quarto veya Calepin not defteri için bir saate kadar. Çağrı zaman aşımına uğradıktan sonra da Oleafly'de çalışmaya devam eder ve Oleafly penceresini gerektiren araçlar onu bekler; bu yüzden yeniden denemeden önce bitmesine izin verin. |
| `compile` hatalar yerine bir neden döndürüyor | Derleme çalışamadı, örneğin TeX kurulu olmadığı için. Oleafly'nin uygulamada sunduğu çözümü, örneğin TinyTeX kurmayı kullanın, sonra yeniden derleyin. |
| Bağlanılamıyor | Oleafly'nin MCP açıkken çalışıyor olması gerekir. Bu sunucu çıkışta durur; uygulama kapalıyken proje araçları için istemciyi bunun yerine `oleafly mcp` komutuna bağlayın. |

## Oleafly'ye dış araçlar ekleyin

![Ayarlar → Yapay Zeka Asistanı → MCP. Bir sunucu ekleyin, kayıt defterine göz atın ya da başka bir araçtaki yapılandırmaları içe aktarın.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Yerleşik asistana daha fazla araç vermek için **Ayarlar → Yapay Zeka Asistanı → MCP** bölümünü açın.

- **Kayıt defterine göz at** ile bir sunucu bulun ve kurulumunu inceleyin.
- **Diğer araçlardan içe aktar** ile var olan sunucu yapılandırmalarını seçin. İçe aktarmadan önce seçili girdileri inceleyin.
- **Sunucu ekle** ile bir sunucuyu kendiniz girin, sonra bağlantıyı doğrulayın.

Bağlı sunucular araçlarını asistana sunar. Bağlantı durumunu inceleyebilir, sunucuları aynı sayfadan açabilir ya da kapatabilirsiniz. Kimlik bilgileri ve komutlar her sunucu yapılandırmasına aittir; yeni bir sunucu bağlamadan önce onları inceleyin.

alphaXiv de bir MCP sunucusu olarak bağlanır, ama onu burada değil, **Ayarlar → Tümleştirmeler → alphaXiv** bölümünde bir API anahtarıyla kurarsınız. Bağlandıktan sonra bu listede **alphaXiv** olarak görünür. Adımları [Araştırma kaynaklarını bağlayın](/docs/integrations/research-sources/#alphaxiv) sayfası anlatır.

## Dış sunucuyu elle yapılandırın

![Sunucu ekle → Form. Yerel komut ya da Uzak URL seçin, bağlantı alanlarını doldurun, sonra Ekle ve doğrula'yı kullanın.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

**Ayarlar → Yapay Zeka Asistanı → MCP** altında **Sunucu ekle**'yi seçin. Yerel bir sunucu stdio üzerinden bir komut çalıştırır; uzak bir sunucu bir URL'ye bağlanır. JSON formu Oleafly'nin sunucu biçimini kullanır:

```json title="Yerel sunucu yapılandırması"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Komutu ve argümanları, kurduğunuz sunucunun belgelediği değerlerle değiştirin. Ortam değerleri `env` nesnesine yazılır.

```json title="Uzak sunucu yapılandırması"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Örnek URL'yi ve belirteci, hizmetin bağlantı ayrıntılarıyla değiştirin. Bağlantıyı denetlemek için **Doğrula**'yı kullanın, sonra sunucunun sunduğu araçları inceleyin. Sunucuyu kendi satırından açın ya da kapatın. Yapılandırmayı değiştirmek için düzenleme eylemini, bağlantıyı kesmek için kaldırma eylemini kullanın.

## Var olan MCP yapılandırmalarını içe aktarın

**Diğer araçlardan içe aktar**'ı seçin, bulunan yapılandırmaları inceleyin ve istediğiniz sunucuları seçin. İçe aktarmadan önce yürütülebilir dosya yollarını, ortam değişkenlerini, URL'leri ve kimlik bilgilerini inceleyin. Bu işlem bağlantı ayarlarını içe aktarır; sunucu yürütülebilir dosyasını sizin için kurmaz.

## Bağlantıyı deneyin

1. Oleafly'de küçük bir alıştırma projesi açın.
2. Uygulamadan kopyaladığınız parçacığı kullanarak dış istemciyi bağlayın.
3. İstemciden `get_status` çağırmasını ve proje dosyalarını listelemesini isteyin.
4. Ana belgeyi okumasını ve bir başlık değişikliği önermesini isteyin.
5. Bir yazma işlemini onaylamadan önce eylemi Oleafly'de inceleyin.
6. Derleyin ve PDF'i inceleyin.

Oleafly içinde bağlı bir dış araç için, o sunucunun desteklediği basit bir salt okunur istekle başlayın ve sohbette oluşan araç kartını inceleyin.
