# MCP sunucusu

> Bir yapay zekâ asistanını MCP ile merkez sunucuya bağlayın. Asistan tesis modelini, cihaz durumunu, günlükleri ve telemetriyi okuyabilir.

Kaynak: https://proxus.io/tr/docs/develop/mcp

Bu kılavuzu tamamladığınızda Model Context Protocol (MCP) destekleyen bir yapay zekâ asistanı merkez sunucunuza
bağlanır. Claude, Cursor ve VS Code bu tür istemcilere örnektir. Asistan; cihazlar, işlem akışları, alarm kuralları ve
alarmlarla ilgili soruları canlı sistemden aldığı bilgiyle yanıtlar. Bunu yaparken oturum açtığı Proxus
kullanıcısının haklarıyla sınırlı kalır.

## Başlamadan önce

Şunlar gereklidir:

- Merkez sunucunun adresi. MCP sunucusu, merkez sunucuyla aynı portta `/mcp` yolunda çalışır, örneğin
  `http://localhost:8080/mcp`.
- Asistana ayrılmış bir Proxus kullanıcısı. Asistanın neyi okuyup neyi değiştirebileceğini bu kullanıcının rolü
  belirler. Ayrıntılar için [Kullanıcılar ve roller](https://proxus.io/tr/docs/administer/users-and-roles) sayfasına bakın.
- Streamable HTTP aktarımını destekleyen bir MCP istemcisi.
- Merkez sunucunun yapılandırmasında `[MCP] Enabled = true` ayarı. Bu ayar varsayılan olarak açıktır.

## Adım 1: Sunucuyu istemcinize ekleyin

```bash
claude mcp add --transport http proxus http://localhost:8080/mcp
```
```json
{
  "servers": {
    "proxus": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}
```
Çoğu istemcide sunucunun URL'sini içeren bir JSON kaydı eklemek yeterlidir:

```json
{
  "mcpServers": {
    "proxus": { "url": "http://localhost:8080/mcp" }
  }
}
```

İstemcide başlık veya anahtar tanımlamanız gerekmez. Oturum açma işlemi bir sonraki adımda, sohbetin içinde yapılır.

## Adım 2: Oturum açın

Oturum açılmadan önce asistan yalnızca araç listesini görebilir ve `schema_overview` aracını çağırabilir. Bu araç
sunucuyu ve oturum açma adımını anlatır. Asistandan oturum açmasını isteyin. Asistan sorduğunda Proxus kullanıcı
adını ve parolasını verin. Asistan bu bilgilerle `auth_login` aracını çağırır.

Oturum yalnızca bu MCP bağlantısı için geçerlidir ve `SessionTtlMinutes` süresi boyunca açık kalır. Varsayılan süre 25
dakikadır. Süre dolduğunda ya da `auth_logout` çağrıldığında asistan bilgileri yeniden ister. Bağlantının hangi
kullanıcıyla açıldığını `auth_whoami` aracıyla görebilirsiniz.

> **Uyarı:**
Parola, asistanla yapılan sohbetin içinden geçer. Bu nedenle yalnızca asistana ayrılmış bir kullanıcı kullanın ve bu
kullanıcıya başka hiçbir yerde kullanılmayan bir parola verin. Kullanıcının rolüne de yalnızca asistanın ihtiyaç
duyduğu hakları tanımlayın.

## Asistanın yapabilecekleri

| Araç | İşlevi | Kimler kullanabilir |
| --- | --- | --- |
| `schema_overview` | Sunucuyu, oturum durumunu ve hangi işte hangi aracın kullanılacağını anlatır. | herkes |
| `auth_login`, `auth_whoami`, `auth_logout` | Oturum açar, oturumdaki kullanıcıyı gösterir, oturumu kapatır. | herkes |
| `schema_entities` | Nesne türlerini (cihazlar, profiller, alarm kuralları, işlem akışları ve diğerleri) ve okunabilen alanlarını listeler. | oturum açmış kullanıcılar |
| `schema_templates` | Nesne oluşturmak için örnek istek gövdeleri verir. | oturum açmış kullanıcılar |
| `schema_protocols` | Bir protokolün bağlantı ayarlarını ve veri noktası adres biçimlerini verir. | oturum açmış kullanıcılar |
| `schema_telemetry` | Saklanan değerler tablosunu ve bu tablonun nasıl sorgulanacağını anlatır. | oturum açmış kullanıcılar |
| `schema_odata_metadata` | Veri modelinin tamamını özetler. | yöneticiler |
| `odata_request` | Nesneleri okur. Yalnızca GET kullanır, her çağrıda en çok 100 nesne döner. | oturum açmış kullanıcılar |
| `odata_mutate` | Kullanıcı tam olarak bu değişikliği istediğinde nesne oluşturur veya değiştirir. | oturum açmış kullanıcılar, rolün izin verdiği ölçüde |
| `device_status` | Kullanıcının görebildiği cihazların anlık çevrim içi veya çevrim dışı durumunu verir. | oturum açmış kullanıcılar |
| `log_query` | Son sistem günlüğü kayıtlarını seviyeye, kaynağa veya metne göre süzerek getirir. | oturum açmış kullanıcılar |
| `telemetry_query` | Saklanan değerler üzerinde salt okunur tek bir SQL sorgusu çalıştırır. Satır, süre ve bellek sınırları uygulanır. | yöneticiler |
| `graph_schema`, `graph_neighbors`, `graph_impact`, `graph_lineage`, `graph_paths`, `graph_context_pack` | Bir cihazın, alarm kuralının, işlem akışının veya panonun nelere bağlı olduğunu ve nelerin ona bağlı olduğunu gösterir ([ilişki haritası](https://proxus.io/tr/docs/organize/operational-graph)). | oturum açmış kullanıcılar |

Sunucu bunlara ek olarak üç hazır istem (prompt) sunar: `proxus_read_entity`, `proxus_write_change` ve
`proxus_analyze_telemetry`. `proxus://schema/` altında da kaynaklar bulunur (overview, entities, telemetry,
templates, protocols).

Her çağrı, oturum açmış kullanıcının izinleriyle çalışır. Rolün izin vermediği bir değişiklik, merkez sunucu
ekranlarında olduğu gibi reddedilir. Silme işlemleri, silme izni olan kullanıcılar için bile varsayılan olarak
engellenir (`BlockDelete = true`).

## Üretim ortamı için güvenliği sıkılaştırın

Aşağıdaki ayarları merkez sunucunun yapılandırmasında `[MCP]` bölümüne yazın. Ortam değişkeni olarak vermek için
`MCP__<Key>` biçimini kullanın.

| Anahtar | Varsayılan | Anlamı |
| --- | --- | --- |
| `Enabled` | `true` | MCP sunucusunu açar veya kapatır. |
| `ServerBaseUrl` | `""` | Merkez sunucunun dışarıdan erişilen adresi, örneğin `https://proxus.example.com`. İstemciler başka makinelerden bağlanacaksa zorunludur. Boş bırakılırsa yalnızca `localhost` üzerinden çalışır. |
| `AllowedBaseUrls` | `[]` | `auth_login` aracının kimlik bilgilerini gönderebileceği diğer Proxus adresleri. Adresler tam olarak eşleşmelidir. |
| `AllowedOrigins` | `[]` | `/mcp` adresini çağırabilecek tarayıcı kaynakları (origin). Tarayıcı dışındaki istemciler origin bilgisi göndermez. |
| `IPWhitelist` | `[]` | Bağlanabilecek adresler veya adres aralıkları, örneğin `["10.0.0.0/8"]`. Boş bırakılırsa tüm adreslere izin verilir. |
| `AdminOnly` | `false` | Korumalı araçları yalnızca yönetici rolündeki kullanıcıların kullanmasına izin verir. |
| `AllowedMethods` | `"GET,POST,PATCH,PUT"` | `odata_mutate` aracının kullanabileceği yöntemler. `"GET"` verilirse asistan yalnızca okuma yapabilir. |
| `BlockDelete` | `true` | Rol izin verse bile silme işlemlerini reddeder. |
| `BlockBulkOperations` | `false` | Tek çağrıda birden çok nesneyi değiştiren işlemleri reddeder. |
| `RateLimitEnabled` | `true` | Kullanıcı başına dakikalık çağrı sınırını etkinleştirir. |
| `RateLimitRequestsPerMinute` | `60` | Tüm çağrılar için dakikalık sınır. |
| `ODataRateLimitRequestsPerMinute` | `30` | `odata_request` ve `odata_mutate` için dakikalık sınır. |
| `TelemetryRateLimitRequestsPerMinute` | `120` | `telemetry_query` için dakikalık sınır. |
| `GraphRateLimitRequestsPerMinute` | `60` | İlişki haritası araçları için dakikalık sınır. |
| `MaxConcurrentSessionsPerUser` | `0` | Bir kullanıcının aynı anda açabileceği MCP oturumu sayısı. `0` sınır olmadığını gösterir. |
| `SessionTtlMinutes` | `25` | Oturumun geçerlilik süresi. |
| `AuditLogging` | `true` | Her çağrıyı kullanıcı, adres, araç ve sonuç bilgisiyle günlüğe yazar. |
| `AnonymousDiscoveryMode` | `"ToolsAndOverview"` | İstemcilerin oturum açmadan önce görebildikleri: `ToolsAndOverview`, `ToolsOnly` veya `Disabled`. |
| `DebugLogging` | `false` | Bağlantı sorunlarını incelemek için istekleri ayrıntılı olarak günlüğe yazar. |

`telemetry_query` aracının sınırları `[MCP.ClickHouse]` bölümünde tanımlanır: `MaxResultRows` (1.000),
`MaxRowsToRead` (10.000.000), `MaxBytesToRead` ve `MaxMemoryUsage` (512 MiB), `MaxExecutionTimeSeconds` (10),
`MaxThreads` (4) ve `MaxResultBytes` (16 MiB). `Username` ve `Password` alanlarına, yalnızca `DeviceRawData` ve
`Logs` tablolarını okuyabilen bir veritabanı kullanıcısının bilgilerini girin.

Birden çok merkez sunucu örneği bir yük dengeleyicinin arkasında çalışıyorsa oturumlar Redis üzerinden paylaşılır.
Bunun için `Cluster:RedisConnection` (veya `MCP:RedisConnection`) ayarının tanımlı olması gerekir.

Reddedilen çağrılar istemciye hata olarak döner. Adrese izin verilmiyorsa `403` döner. Yönetici rolü olmayan bir
kullanıcı yönetici aracını çağırırsa `authorization_denied` hatası alır. Oturum açmadan korumalı bir araç
çağrılırsa `401`, çağrı sınırı aşılırsa `429` döner.

## Sonraki adımlar

- [REST API](https://proxus.io/tr/docs/develop/rest-api): aynı veriye kendi programlarınızdan erişin.
- [İlişki haritası](https://proxus.io/tr/docs/organize/operational-graph): ilişki haritası araçlarının okuduğu yapıyı tanıyın.
- [Güvenliği sıkılaştırma](https://proxus.io/tr/docs/operate/security): merkez sunucu ve Edge Gateway'ler için güvenlik ayarlarını gözden geçirin.