AI Ajanlarını MCP ile Bağlama | Proxus Dokümantasyon

Proxus MCP Server, uyumlu AI ajanlarına endüstriyel veri platformunuzu anlamaları ve platformla çalışmaları için yönetişimli bir yol sunar. Ajan; doğrudan veritabanı veya kontrol sistemi kimlik bilgilerini almadan canlı veri modelini keşfedebilir, güncel cihaz sağlığını okuyabilir, operasyonel bağımlılıkları izleyebilir, telemetriyi inceleyebilir ve izin verilen varlık işlemlerini kullanabilir.

Proxus MCP kanıtlarından üretilen operasyon raporu

info

Doğru rehberi seçin

Bu sayfa bir AI ajanını bağlayan ve kullanan kişiler içindir. Platform sahipleri; güvenli devreye alma, izinler, production endpoint hazırlığı, limitler ve audit operasyonları için MCP Server Yönetimi rehberini kullanmalıdır.

Beş Dakikada Bağlantı

1. MCP endpoint'ini alın

Proxus Hub tarafından sunulan Streamable HTTP endpoint'ini kullanın:

https://proxus-adresiniz.example/mcp

Lokal geliştirme dışında HTTPS kullanın. Tool argument'ları içinde ikinci bir hedef eklemeyin veya farklı bir sunucu adresi göndermeyin.

2. Proxus'u ajanınıza ekleyin

MCP uyumlu istemcinize şu değerlerle uzak bir sunucu ekleyin:

Ayar	Değer
Transport	Streamable HTTP
URL	Proxus `/mcp` endpoint'iniz
Kimlik doğrulama	Bağlantıdan sonra `auth_login` aracıyla yapılır

İstemci konfigürasyon formatları zaman içinde değişebilir. İstemcinizin desteklediği güncel uzak MCP sunucu formunu kullanın ve yukarıdaki endpoint'i hedefleyin.

3. Ajanın çalışma akışını keşfetmesine izin verin

İlk yararlı çağrı:

schema_overview()

Yanıt; kimlik doğrulama durumunu, kullanılabilir veri yüzeylerini, güvenli çalışma kurallarını, aktif tool kataloğunu ve sık görevler için doğru aracı açıklar. Proxus'u tanımayan bir ajan başlamak için ayrıca yazılmış bir ana prompt'a ihtiyaç duymaz.

4. İstendiğinde kimlik doğrulayın

Korumalı bir işten önce ajan şunu çağırmalıdır:

auth_whoami()

Kimlik doğrulama gerektiğinde ajan durmalı ve insana hangi Proxus hesabını kullanacağını sormalıdır. Ardından şu çağrıyı yapar:

auth_login(userName: "insan-tarafından-verilen-kullanıcı", password: "insan-tarafından-verilen-parola")

İki özellik de zorunludur. Boş parola yalnız insan seçilen hesabın gerçekten boş parolası olduğunu açıkça doğruladığında geçerlidir. Protocol-bound girişten sonra istemci aynı MCP transport oturumunu yeniden kullanır ve session kimliklerini elle taşımaz.

5. Operasyonel bir soru sorun

Örnekler:

Hangi cihazları görebiliyorum ve güncel runtime durumları nedir?
Bu tag'i hangi Rule, Function ve Dashboard'lar kullanıyor?
DeviceProfile 54 değişirse neler etkilenebilir?
Alert 28'i telemetri kanıtına kadar izle.
Son 24 saatte telemetri sürekliliği sorunu olan cihazları bul.

Ajan Otomatik Olarak Ne Öğrenir?

Proxus, kullanıcı tarafından yazılmış bir ana prompt'a bağımlı kalmadan protocol-native yüzeyler üzerinden bağlı ajanı eğitir.

Yüzey	Ajana öğrettiği bilgi
Sunucu talimatları	Kimlik doğrulama, read-only varsayılanı, kanıt sınırları, redaction ve güvenli recovery kuralları
`tools/list`	Güncel araçlar, input şemaları, zorunlu argument'lar, izinli değerler ve güvenlik işaretleri
`schema_overview`	Görevden araca yönlendirme, aktif yetenekler, oturum durumu ve katalog revizyonu
Şema araçları	Canlı varlık alanları, telemetri düzeni, şablonlar ve protokol kavramları
Yapılandırılmış diagnostic'ler	Çağrının neden başarısız olduğu ve deterministik sonraki adım

Bir aracın görünür olması izin verildiği anlamına gelmez. Korumalı araçlar discovery sırasında görünebilir ve mevcut Proxus kullanıcısı kimlik doğrulayıp yetki alana kadar çağrıyı reddedebilir.

Görev Yönlendiricisi

Kullanıcı amacı	İlk araç	Devam aracı
Proxus'un ne sunduğunu anlamak	`schema_overview`	Önerilen şema veya görev aracı
Gerçek varlık ve alan adlarını keşfetmek	`schema_entities`	`odata_request`
Güncel cihaz sağlığını kontrol etmek	`device_status`	Gerektiğinde hedefli graph veya telemetri incelemesi
Yakın bağımlılıkları görmek	`graph_schema`	`graph_neighbors`
Downstream değişiklik etkisini değerlendirmek	`graph_impact`	Nedensel zincir için `graph_paths`
Upstream kaynakları izlemek	`graph_lineage`	Kompakt AI bağlamı için `graph_context_pack`
Telemetriyi incelemek	`schema_telemetry`	Bir veya daha fazla sınırlı `telemetry_query` çağrısı
Son operasyon loglarını görmek	`log_query`	Daha dar gateway ve zaman filtreleri
Konfigürasyon veya kayıt okumak	`schema_entities`	Açık alan seçimiyle `odata_request`
Açıkça istenen değişikliği uygulamak	Önce hedefi okuyun	`odata_mutate`, ardından `odata_request` ile doğrulayın

Kanıt Türlerini Ayrı Tutun

Doğru çalışan bir ajan farklı gerçeklik türlerini tek bir duruma indirmemelidir.

Kanıt	Doğru kaynak	Anlamı
Kalıcı konfigürasyon	`odata_request`	Neyin yapılandırıldığı ve etkin olduğu
Güncel cihaz sağlığı	`device_status`	Hub kanıtı ve freshness üzerinden runtime kullanılabilirliği
Gateway bağlantısı	`device_status` ve graph metadata	Gateway runtime'ın şu anda bağlı olup olmadığı
Desired deployment	Operational Graph	Hub'ın edge runtime'a uygulatmak istediği durum
Son bilinen edge confirmation	Operational Graph	Bir revizyonun uygulandığına ilişkin advisory kanıt
Telemetri gözlemi	`telemetry_query`	Tanımlı zaman penceresinde ölçülen değer

AppliedByEdge veya InSync, cihazın şu anda online olduğunu ya da veri ürettiğini kanıtlamaz. Kalıcı Connected ve Status alanları device_status yerine kullanılmamalıdır.

Temel Çalışma Akışları

Güncel Cihaz Envanteri

1. auth_whoami()
2. device_status(maxDevices: 100)
3. Online, OfflineOrStale, Unknown ve Redacted sonuçlarını ayrı raporla
4. evaluatedAtUtc, freshness, omitted count ve Enabled konfigürasyonunu ekle

Hedefli kontrol için kesin deviceOids değerlerini kullanın. OData kayıtlarından canlı bağlantı çıkarımı yapmayın.

Bağımlılık ve Etki Analizi

1. graph_schema()
2. graph_neighbors(entityType: "DeviceProfile", oid: "54", direction: "Both", depth: 1)
3. graph_impact(entityType: "DeviceProfile", oid: "54", depth: 2)
4. graph_paths(entityType: "DeviceProfile", oid: "54", direction: "Outgoing", goal: "bakım değişikliği etkisi")

Graph yönü her zaman upstream kaynak veya sebepten downstream tüketici veya etkiye doğrudur. Impact outgoing edge'leri, lineage incoming edge'leri izler.

Canonical entityType ve oid argument adlarını kullanın. key, oid için alias değildir. Geçersiz argument'lar; ajanın tahmin yürütmeden çağrıyı düzeltebilmesi için eksik, beklenmeyen, geçersiz ve kabul edilen argument adlarıyla tool_arguments_invalid döndürür.

Alarmdan Telemetri Kanıtına

1. OData ile Alert kimliğini ve zamanını seç
2. graph_lineage(entityType: "Alert", oid: "28", depth: 4)
3. Kanıtlanan Rule, cihaz ve telemetri key veya series değerini belirle
4. schema_telemetry()
5. Alert zamanı çevresinde dar bir UTC penceresi sorgula
6. Ölçülen değeri Alert kanıtıyla karşılaştır

Her ilişkinin kalıcı konfigürasyondan, desired runtime durumundan, parse edilmiş semantikten veya gözlenen telemetriden gelip gelmediğini raporlayın. Sınırlı graph sonucunu başka bağımlılık bulunmadığının kanıtı olarak sunmayın.

Sınırlı Telemetri İncelemesi

telemetry_query, yalnız yönetici rolüne açık ve korumalı bir okuma yüzeyidir. Sorgu oluşturmadan önce schema_telemetry çağırın.

Öngörülebilir performans için:

Önce soruyu tanımlayın: freshness, gap, threshold, spike, trend, variance veya peer deviation.
Kesin cihaz kimliklerini, ilgili telemetri key'lerini ve sınırlı UTC zaman penceresini kullanın.
Geniş analizi raw satır döndürmeden önce aggregate edin.
LIMIT değerini tarama sınırı değil, çıktı sınırı olarak yorumlayın.
query_resource_limit_exceeded sonucunda aynı sorguyu tekrarlamak yerine yeniden planlayın.
Kapsamı raporlayın: cihazlar, key'ler, zaman penceresi, başarısız scope'lar ve kalan belirsizlik.

Örnek:

SELECT
    DeviceId,
    Key,
    argMax(NumericValue, Time) AS LatestValue,
    max(Time) AS LastActivity
FROM DeviceRawData
PREWHERE DeviceId = 470
    AND Key = 'Temperature'
    AND Time >= now() - INTERVAL 1 HOUR
GROUP BY DeviceId, Key
LIMIT 10

Sunucu her çağrıda tek korumalı SELECT veya SELECT tabanlı CTE kabul eder. Tek analiz birden fazla sınırlı çağrı kullanabilir.

Yönetişimli Varlık Okuma

OData oluşturmadan önce canlı sözleşmeyi keşfedin:

1. schema_entities()
2. Canonical varlığı ve yalnız selectableFields alanlarını seç
3. odata_request(path: "api/odata/Device?$select=Oid,DeviceName,Enabled&$top=20")

Varlık okumaları açık alan projection ister. Desteklenmeyen navigation, geniş expansion, kısıtlı alanlar ve raw metadata erişimi fail-closed reddedilir.

Açık Değişiklik Talebi

İnsan belirli bir değişikliği istemediği sürece MCP read-only kalır. Güvenli yazma akışı:

1. Kesin hedefi ve istenen sonucu insanla doğrula
2. Mevcut kaydı oku
3. schema_overview içindeki aktif mutation yeteneklerini kontrol et
4. Tek hedef, izinli method, minimal body ve doğru changeIntent ile odata_mutate çağır
5. Hedefi tekrar oku ve doğrulanan sonucu raporla

“Bir şey değiştir” yeterli yetki değildir. Silme ve bulk davranışı sunucu konfigürasyonu ve kullanıcı izinleriyle ayrıca kontrol edilir.

Operational Graph Kanıtı

Her graph edge'i şunları taşır:

Alan	Anlamı
`Relation`	Kararlı ilişki adı
`SourceKindName`	`ConfigTyped`, `RuntimeDesired`, `ParsedCriteria`, `ParsedDashboard`, `RuntimeObserved` veya `ParsedFunction`
`ConfidenceName`	`High`, `Medium` veya `Low`
`Evidence`	Edge'in neden var olduğuna ilişkin sanitize açıklama
`ExtractorId`	Kararlı, versioned kaynak kimliği

Numeric source-kind ve confidence alanları compatibility için korunur. İnsan tarafından okunabilir ajan cevaplarında name alanlarını, entegrasyonlarda ExtractorId değerini kullanın.

Tamlık iddiasından önce Diagnostics, Redactions, Limits, omitted count ve Snapshot tutarlılığını kontrol edin. Raw function code, credential, connection parameter, notification secret ve raw dashboard SQL döndürülmez.

Tool Kataloğu

Grup	Araçlar
Kimlik doğrulama	`auth_login`, `auth_logout`, `auth_whoami`
Runtime	`device_status`
Şema	`schema_overview`, `schema_entities`, `schema_odata_metadata`, `schema_telemetry`, `schema_templates`, `schema_protocols`
Graph	`graph_schema`, `graph_neighbors`, `graph_impact`, `graph_lineage`, `graph_paths`, `graph_context_pack`
Telemetri ve log	`telemetry_query`, `log_query`
Yönetişimli varlıklar	`odata_request`, `odata_mutate`

schema_odata_metadata ve telemetry_query yönetici Proxus rolü gerektirir. Diğer korumalı araçlar kimliği doğrulanmış kullanıcının izinlerini kullanır; alan ve nesneleri filtreleyebilir veya redakte edebilir.

Resources, Prompts ve Completions

Uyumlu istemciler şunları da kullanabilir:

Yetenek	Örnekler
Resources	Platform özeti, varlık şeması, telemetri şeması, varlık şablonları ve protokol tanımları
Prompts	Güvenli varlık okuma, kontrollü değişiklik ve telemetri analizi akışları
Completions	Desteklenen prompt ve resource-template argument'ları için izinli değerler

Bunlar isteğe bağlı hızlandırıcılardır. Yalnız tools desteği olan istemciler için sunucu talimatları, tool şemaları ve schema_overview yeterlidir.

İstemci ve Katalog Notları

Sunucu sürümünü değiştirirken veya tool discovery test ederken yeni MCP transport açın.
auth_login, Proxus business session'ını yeniler; istemcinin cache'lenmiş tool kataloğunu yenilemez.
İstemci kaldırılmış bir tool gösteriyorsa veya schema_overview içinde adı geçen aracı bulamıyorsa tamamen yeniden bağlanıp tools/list yenileyin.
Sunucu initialization sonrasında standart tool-list change notification gönderir; istemci bunu uygulamalıdır.
Normal protocol-bound akışta tool argument'larında compatibility session kimliği veya cookie gerekmez.

Yapılandırılmış Hatalardan Kurtulma

Classification	Yapılacak işlem
`authentication_required`	İnsana Proxus hesabını sorun ve `auth_login` çağırın
`authentication_input_required`	İnsan tarafından verilen iki login özelliğini de gönderin
`tool_arguments_invalid`	`requiredInputs` ve `acceptedArguments` ile aynı aracı yeniden çağırın
`tool_catalog_stale`	MCP transport'u yeniden bağlayıp `tools/list` yenileyin
`odata_select_required`	`schema_entities` çağırıp sınırlı projection oluşturun
`query_resource_limit_exceeded`	Telemetri sorgusunu yeniden planlayın; limitleri zayıflatmayın veya aynı sorguyu tekrarlamayın
`authorization_denied`	Durun; mevcut Proxus rolü bu işleme izin vermiyor
`endpoint_not_allowed` veya `origin_not_allowed`	Yönetici tarafından onaylanan MCP endpoint'ini kullanın
`graph_query_unavailable`	Aynı sınırlı graph sorgusunu bir kez tekrarlayın, ardından diagnostic'i raporlayın

Ajan çıktısında session kimliği, parola, token, cookie, credential, function code, connection parameter veya raw SQL göstermeyin.

Sonraki Adımlar

MCP Server Yönetimi — production devreye alma, izinler, limitler ve güvenlik operasyonları
Konfigürasyon Referansı — canonical MCP ayarları ve environment override'ları
Güvenlik ve Kullanıcılar — platform rolleri ve izinleri
UNS Konu İzinleri — path tabanlı UNS erişimi
REST API — doğrudan uygulama entegrasyonu