# Web sitenizi ajanlara hazırlamak: llms.txt, Markdown sayfalar, OpenAPI, api-catalog ve MCP sunucu kartları

_2026-10-03 · Ajanlara hazır bir site ne yayınlar: llms.txt, sayfaların Markdown sürümleri, OpenAPI, RFC 9727 api-catalog ve MCP sunucu kartı. Örnek: shager.ai._

Ajanlara hazır bir web sitesi, yazılıma "bu nedir?" sorusundan "bunu nasıl kullanırım?" sorusuna giden kısa ve öngörülebilir bir yol sunar. Pratikte bu, beş dosya ya da kural anlamına gelir: bir `/llms.txt` özeti, her sayfanın temiz Markdown sürümü, API'nin OpenAPI tanımı, bu tanımı gösteren bir RFC 9727 `/.well-known/api-catalog` ve nasıl bağlanılacağını anlatan bir MCP sunucu kartı. Hiçbirini yayınlamak zor değil. Birlikte, bir ajanın bir ürünü bulmasını, anlamasını ve bir insanın sohbete URL kopyalamasına gerek kalmadan kullanmaya başlamasını sağlarlar.

Yazı boyunca örnek olarak shager.ai'yi kullanacağım, çünkü burada anlatılan her parça orada canlı ve okurken her birini `curl` ile çekebilirsiniz.

## Hiçbir motor bu dosyaları okuyacağını vaat etmiyorsa neden uğraşalım?

Önce dürüst olalım. `llms.txt` onaylanmış bir standart değil, bir öneri; büyük model sağlayıcılarından herhangi birinin onu bilgi getirmede kullanacağını açıkça taahhüt ettiğinden haberim yok. api-catalog gerçek bir IETF RFC'si, MCP sunucu kartları da kabul edilmiş bir MCP uzantısı; ama tarayıcılar ve istemciler tarafından benimsenmeleri henüz çok yeni.

Yine de yapmanın gerekçesi pratik. Ajanlar bir siteye giderek daha sık, bir insan onlara "buna kaydol ve bağla" dediği için geliyor. O anda ajan sayfaları doğrudan çeker. Temiz Markdown ile, açık bir API tanımı ve bağlantı tarifiyle yanıt veren bir site doğru kullanılır. 400 KB JavaScript ile yanıt veren bir site ise tahminle kullanılır.

## llms.txt: ön kapı

Format [llmstxt.org](https://llmstxt.org/) adresinde tanımlanmıştır. `/llms.txt` yolunda duran bir Markdown dosyasıdır: siteyi adlandıran bir H1 (zorunlu olan tek kısım), alıntı bloğu biçiminde bir özet, isteğe bağlı serbest metin ve kısa notlarla birlikte link listeleri içeren H2 bölümleri. "Optional" başlıklı bir bölüm, ajanın daha kısa bir bağlama ihtiyaç duyduğunda atlayabileceği linkleri işaretler.

Shager'ın dosyası bu yapıyı izler. Başı şöyle görünür:

```markdown
# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and
> marketers: your agent creates, Shager ships it everywhere. ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (OAuth sign-in for any MCP client that supports it, or Authorization: Bearer <api key>)
- REST API: https://app.shager.ai/api/v1 ...
- Self sign-up: POST https://app.shager.ai/api/v1/agent/signup ...
```

Örnek alınmaya değer birkaç tercih var. Ajan bölümü pazarlama sayfalarından önce gelir, çünkü dosyayı okuyan bir ajan genellikle harekete geçmek ister. Fiyatlar bir linkin arkasına saklanmak yerine dosyanın içinde düz rakamlarla yazılıdır. Sınırlar açıkça belirtilir (örneğin TikTok uygulamayı onaylayana kadar TikTok gönderileri gizli kalır); böylece ajan, kullanıcıya ürünün henüz yapamadığı bir şeyi vaat etmez. Tek seferde çekmeyi tercih eden ajanlar için de tüm içeriği tek dosyada toplayan bir `/llms-full.txt` eşlik eder.

## Her sayfanın Markdown sürümü

Aynı öneri, her sayfanın temiz bir Markdown sürümünün sunulmasını ve bunun `rel="alternate"` ile `type="text/markdown"` kullanılarak duyurulmasını, ayrıca sayfayı kapsayan `llms.txt` dosyasını gösteren bir `rel="describedby"` eklenmesini tavsiye eder. İkisi de HTML `<link>` öğesi ya da HTTP `Link` başlığı olabilir.

Shager bunu iki yolla yapar. Her sayfanın `/md/` altında bir Markdown ikizi vardır; yani `/en/pricing` aynı zamanda `/md/en/pricing` adresinde de bulunur. Normal URL'ye `Accept: text/markdown` ile yapılan bir istek de doğrudan Markdown'ı alır:

```bash
curl -s -H "Accept: text/markdown" https://shager.ai/en/pricing | head -5
```

Her HTML sayfası alternatiflerini duyuran bir `Link` başlığı da gönderir:

```http
link: </.well-known/api-catalog>; rel="api-catalog",
      </llms.txt>; rel="describedby"; type="text/plain",
      </md/en/agents>; rel="alternate"; type="text/markdown"
```

Arama açısından önemli bir ayrıntı: Markdown yanıtları `x-robots-tag: noindex` taşır, böylece arama motorları her sayfanın iki kopyasını dizine eklemez. Markdown ajanlar içindir; insanlar ve arama sonuçları için kanonik sayfa HTML olmaya devam eder.

## OpenAPI: sözleşme

Bir ajanın çağıracağı her şey için [OpenAPI](https://spec.openapis.org/oas/v3.1.0) belgesi hâlâ yayınlayabileceğiniz en yararlı şeydir. İşlem kimliklerini, parametreleri, şemaları ve kimlik doğrulamayı hem ajanların hem de kod üreticilerin okuyabildiği bir biçimde verir.

Shager'ınki [app.shager.ai/api/v1/openapi.json](https://app.shager.ai/api/v1/openapi.json) adresinde, 3.1 sürümünde. İçindeki üç kural özellikle ajanlara yardımcı olur. İşlem kimlikleri MCP araç adlarıyla aynıdır (`create_post`, `get_analytics`); böylece bir arayüzü öğrenen ajan diğerini de bilir. Her işlem, gereken anahtar yetkisini bir `x-scope` uzantısında belirtir. Alan açıklamaları da talimat olarak yazılmıştır; örneğin `per_channel` açıklama geçersiz kılma alanı, ifadelerin hesaba göre çeşitlendirilmesinin önerildiğini söyler. Açıklamalar istem alanıdır; onları kullanın.

## api-catalog: yazılıma API'lerin nerede olduğunu söylemek

IETF tarafından Haziran 2025'te yayımlanan [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727), iyi bilinen bir URI (`/.well-known/api-catalog`) ve bir `api-catalog` link ilişkisi tanımlar. Bu adrese yapılan istek, bir yayıncının API'lerini açıklamalarına ve belgelerine giden linklerle listeleyen bir belge döndürür. RFC, belge için `application/linkset+json` medya türünü zorunlu tutar ve OpenAPI gibi makinece okunabilir açıklamalar için `service-desc`, insanlara yönelik belgeler için `service-doc` gibi link ilişkileri kullanır.

Shager'ın kataloğunun tamamı şu:

```json
{
  "linkset": [
    {
      "anchor": "https://app.shager.ai/api/v1",
      "service-desc": [
        { "href": "https://app.shager.ai/api/v1/openapi.json", "type": "application/openapi+json" }
      ],
      "service-doc": [
        { "href": "https://shager.ai/en/agents", "type": "text/html" },
        { "href": "https://shager.ai/md/en/agents", "type": "text/markdown" }
      ]
    }
  ]
}
```

Kısa, çünkü Shager'ın tek bir API'si var. Birden fazla API'si olan bir şirket her API için bir kayıt listeler. Yukarıda gösterilen, her sayfanın `Link` başlığındaki `rel="api-catalog"` linki, herhangi bir sayfaya gelen bir istemcinin yolu tahmin etmeden kataloğu bulmasını sağlar.

## MCP sunucu kartları: bağlanmadan önce nasıl bağlanılacağı

Bir MCP istemcisinin `tools/list` çağrısını yapabilmesi için sunucunun nerede olduğunu ve nasıl kimlik doğrulayacağını bilmesi gerekir. [SEP-2127](https://modelcontextprotocol.io/seps/2127-mcp-server-cards), tam da bunun için MCP Server Cards'ı tanımlar: uzak bir sunucunun kimliğini, aktarım uç noktalarını, gerekli başlıkları ve desteklenen protokol sürümlerini anlatan statik bir JSON belgesi. SEP, önerilen konum olarak `<streamable-http-url>/server-card` yolunu ayırır ve kartlara link veren bir AI Catalog üzerinden alan adı düzeyinde keşfi anlatır. Ayrıntılı şema, uzantının deposunda yer alır.

Shager kartını önerilen konum olan `https://app.shager.ai/api/mcp/server-card` adresinde ve bazı keşif araçlarının yokladığı `https://shager.ai/.well-known/mcp/server-card.json` yolunda sunar. Bağlantı kısmı şöyle:

```json
{
  "name": "ai.shager/shager",
  "title": "Shager",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": [
        { "name": "Authorization", "isRequired": true, "isSecret": true,
          "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)" }
      ]
    }
  ]
}
```

Kart, Shager'ın araçlarını tek satırlık açıklamalarla da listeler. Dikkat edin: SEP araçları bilerek standart kart alanlarının dışında tutar, çünkü bir sunucunun sunduğu araçlar kullanıcıya ve oturuma göre değişebilir. Karttaki herhangi bir araç listesini bir ön izleme olarak görün; doğruluğun kaynağı canlı `tools/list` çağrısıdır.

## İki ek: auth.md ve bir beceri dosyası

Keşif, ajana neyin var olduğunu söyler. İki dosya daha ona ne yapacağını söyler.

[/auth.md](/auth.md), bir ajanın nasıl erişim elde ettiğini anlatan sade bir tariftir: keşfet, kendi kendine kayıt çağrısıyla kaydol, anahtarı kullan, sahiplenme linkini bir insana ilet ve insanın erişimi nasıl iptal edeceği. Kuralları da belirtir: istek sınırı, hata yapısı, açıklama çeşitlemesi, yalnızca resmi API'ler. Bir ajan onu baştan sona izleyebilir.

`https://shager.ai/skills/shager/SKILL.md`, Claude Code'un [beceriler (skills)](https://code.claude.com/docs/en/skills) için kullandığı formatta bir beceri dosyasıdır: bir `name` ve modele onu ne zaman kullanacağını söyleyen bir `description` içeren YAML ön bilgisi, ardından numaralı talimatlar. Kurduğunuzda ajan, uzun bir isteme gerek kalmadan Shager iş akışını bilir. Kendi sürümünüzü oluşturmayı [Shager için bir Claude becerisi oluşturmak](/en/blog/build-a-claude-skill-for-shager) yazısında anlatıyoruz.

## Kendi siteniz için kontrol listesi

1. Bir H1, tek paragraflık bir özet, en başta bir ajan bölümü ve canlı olmayan her şey için dürüst etiketler içeren `/llms.txt`.
2. Her sayfanın `rel="alternate"` ve `type="text/markdown"` ile duyurulan, `noindex` olarak işaretlenmiş bir Markdown sürümü.
3. İşlem kimlikleri MCP araçlarınızla aynı olan ve açıklamaları talimat olarak yazılmış bir OpenAPI belgesi.
4. `application/linkset+json` olarak sunulan ve her sayfadan `rel="api-catalog"` ile link verilen `/.well-known/api-catalog`.
5. `<your MCP URL>/server-card` adresinde bir MCP sunucu kartı.
6. Ajanlar kaydolabiliyorsa, `auth.md` gibi sade dilde yazılmış bir erişim tarifi.

## SSS

### llms.txt ile robots.txt aynı şey mi?

Hayır. `robots.txt` tarayıcılara neyi çekebileceklerini söyler. `llms.txt` ise dil modelleri için yazılmış, okunmaya değer olanların seçilmiş bir rehberidir. Hiçbir izin vermez ya da reddetmez.

### Bu dosyaları yayınlamak arama sıralamasını iyileştirir mi?

Bunu gösteren yayımlanmış bir kanıt yok ve hiçbir arama motoru `llms.txt` dosyasını sıralama sinyali olarak kullandığını söylemedi. Değer, ajanların sitenize geldikten sonra ürününüzü doğru kullanmasında. HTML sayfalarınızı arama için kendi başlarına güçlü tutun.

### Bundan yararlanmak için bir MCP sunucusuna ihtiyacım var mı?

Hayır. `llms.txt`, Markdown sayfalar, OpenAPI ve api-catalog, belgesi ya da API'si olan her site için yararlıdır. Sunucu kartı yalnızca uzak bir MCP sunucusu çalıştırıyorsanız geçerlidir.

## Buradan nereye?

Shager'ın dosyalarını `curl` ile çekin ve kendi sitenizle karşılaştırın. Ajanın keşiften sonra ne yaptığını görmek için sıradaki durak [ajan giriş noktası](/en/agents).

---
Source: https://shager.ai/tr/blog/agent-ready-websites-llms-txt