Teamso MCP Sunucusu

MCP nedir?

Model Context Protocol (MCP), yapay zekâ asistanlarının dış sistemlerdeki araçları çağırmasını sağlayan açık bir standarttır. Teamso'nun hosted MCP sunucusu https://mcp.teamso.com/v1 adresinde, Streamable HTTP ve özel başlık destekleyen istemcilere hizmet verir.

Claude Desktop uzak bağlantılarda OAuth istediğinden yerel npm paketini (@teamso/teamso-mcp) kullanır. Her istek kişisel erişim token'ınızla ve sizin yetkilerinizle çalışır; sunucu token'ı saklamaz.

Bağlantılar

• MCP spesifikasyonu
• GitHub deposu
• npm paketi
• Erişim token'ı oluştur
• Self-hosted MCP kılavuzu

Kurulum

İstemcinizi seçin. Hepsi aynı token'ı kullanır: Teamso'da sol menünün en altındaki MCP erişimi sayfasını açıp token oluşturun ve örneklerdeki tms_pat_... yerine yazın.

Cursor

1. Cursor'da Cmd+Shift+P → Open MCP settings komutunu çalıştırın.
2. Sunucuyu ~/.cursor/mcp.json dosyasına ekleyin:

{
  "mcpServers": {
    "teamso": {
      "url": "https://mcp.teamso.com/v1",
      "headers": {
        "Authorization": "Bearer tms_pat_..."
      }
    }
  }
}

Cursor'u yeniden başlatın; Teamso araçları MCP listesinde görünür.

Claude Code

Terminalde tek komut:

claude mcp add --transport http teamso https://mcp.teamso.com/v1 --header "Authorization: Bearer tms_pat_..."

Kontrol için claude mcp get teamso çalıştırın ya da Claude Code içinde /mcp yazın.

claude mcp get teamso

Claude Desktop

Claude Desktop'ta uzak özel bağlayıcılar (Custom Connectors) OAuth ister; Teamso token kullandığı için yerel paketi kullanın. claude_desktop_config.json dosyasına ekleyin ve Claude Desktop'u tamamen kapatıp açın:

{
  "mcpServers": {
    "teamso": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@teamso/[email protected]"
      ],
      "env": {
        "TEAMSO_ACCESS_TOKEN": "tms_pat_..."
      }
    }
  }
}

Sürümü sabitleyin (@1.2.1): sabitlenmemiş npx önbellekteki eski sürümü çalıştırmaya devam eder. Adresi Connectors listesine eklemeyin.

Claude Desktop bağlantı sorunları

• Yapılandırma hatası: girdi type, command, args ve env alanlarını içermeli.
• Araçlar görünmüyor: Node.js 20 ya da üstü kurulu olmalı; Claude Desktop'u menüden tamamen kapatıp yeniden açın.
• Çağrılar hemen düşüyor: paket sürümünü sabitleyin; npx önbellekteki eski sürümü kullanıyor olabilir.
• Yapılandırmaya timeout alanı eklemeyin; istemci onu yok sayabilir.

Windsurf

Windsurf → Settings → MCP (~/.codeium/windsurf/mcp_config.json). Windsurf adresi serverUrl alanında bekler:

{
  "mcpServers": {
    "teamso": {
      "serverUrl": "https://mcp.teamso.com/v1",
      "headers": {
        "Authorization": "Bearer tms_pat_..."
      }
    }
  }
}

Diğer istemciler

Streamable HTTP destekleyen her istemci https://mcp.teamso.com/v1 adresine Authorization: Bearer tms_pat_... başlığıyla bağlanır. Yalnız stdio destekleyen istemciler hosted sunucuya mcp-remote ile ulaşır:

{
  "mcpServers": {
    "teamso": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.teamso.com/v1",
        "--header",
        "Authorization:Bearer ${TEAMSO_TOKEN}"
      ],
      "env": {
        "TEAMSO_TOKEN": "tms_pat_..."
      }
    }
  }
}

Yalnız OAuth ile bağlanabilen istemciler desteklenmez.

Kimlik doğrulama

Teamso MCP kişisel erişim token'ı (tms_pat_...) kullanır. Token'ı Teamso'da sol menünün en altındaki MCP erişimi sayfasında oluşturun; yalnız oluşturulduğu anda bir kez gösterilir.

Authorization: Bearer tms_pat_...

• Token sizin hesabınızla ve güncel yetkilerinizle çalışır: ekranda göremediğiniz veriyi MCP ile de göremezsiniz.
• Her istek Authorization: Bearer tms_pat_... başlığını taşır; hosted sunucu token'ı saklamaz, isteği Teamso API'sine iletir.
• Geçerlilik 30 gün, 90 gün, 1 yıl ya da süresizdir ve bir kullanıcının en fazla 10 etkin token'ı olabilir; token'ı aynı sayfadan istediğiniz an iptal edebilirsiniz.
• Şifre, oturum ve giriş kanalı (telefon, e-posta) işlemleri, token yönetimi, entegrasyon anahtarları ve SGK şifreleri, şirket güvenlik ayarları, destek erişimi, şirket silme ve webhook değişiklikleri token'la yapılamaz (403 ACCESS_DENIED).
• Şirketinizde IP kısıtlaması varsa token'la gelen istekler de bu kurala tabidir; hosted sunucu gerçek istemci IP'nizi imzalayarak iletir.
• Token'la yapılan yazmalar denetim kaydına MCP kaynağıyla düşer.
• Kullanıcı pasife alınır ya da başka bir şirkete geçerse token çalışmaz.

Araçlar

Hosted sunucu ve npm paketi aynı 34 aracı sunar. Her araç tipli girdi ve çıktı şeması, structuredContent ve kısa bir metin yanıtı döndürür. Hangi aracı kullanabileceğiniz rolünüze ve yetkilerinize bağlıdır.

Distribütör hesabı hosted sunucuda ayrıca Landing CMS içerik prompt'larını (seo_landing_page, translate_marketing_content) görür; hosted sunucu bunları Teamso API'sinden alır.

Tüm modüller

Bu sayfadaki hazır araçlar en sık işler içindir. Geri kalan her şey için (masraf, talep, fazla mesai, PDKS, puantaj, vardiya, işe alım, işe alışma, demirbaş, belge onayı, anket, raporlar, şirket ayarları...) asistan genel API araçlarını kullanır. Araçlar Teamso API'sinin size özel uç kataloğunu okur: yalnız sizin yetkinizin açtığı uçlar listelenir ve çağrılabilir. Örneğin izin ekleme yetkiniz yoksa asistan da MCP üzerinden izin ekleyemez.

Nasıl ilerler?

1. find_api_endpoints ya da list_api_modules ile uygun ucu bulur.
2. describe_api_endpoint ile parametreleri, gövde şemasını ve SMS kodu gerekip gerekmediğini öğrenir.
3. Okumalar için call_api_read: sonucu doğrudan döndürür.
4. Değişiklikler için call_api_write: önce önizleme gösterir, ancak siz onaylayınca confirm: true ile çalıştırır.

Arama, uç kimliklerini (YÖNTEM /yol) ve her ucun etkisini döndürür:

{
  "name": "find_api_endpoints",
  "arguments": {
    "query": "masraf",
    "side_effect": "read"
  }
}

{
  "structuredContent": {
    "query": "masraf",
    "sideEffect": "read",
    "page": 1,
    "size": 20,
    "total": 2,
    "totalPages": 1,
    "endpoints": [
      {
        "id": "GET /expense-form/{id}",
        "module": "EXPENSE",
        "summary": "Masraf formu ayrıntısı",
        "sideEffect": "read",
        "smsCodeRequired": "never",
        "fileResponse": false
      },
      {
        "id": "GET /expense-form/listPagination",
        "module": "EXPENSE",
        "summary": "Masraf formları (sayfalı)",
        "sideEffect": "read",
        "smsCodeRequired": "never",
        "fileResponse": false
      }
    ]
  }
}

Okuma, kimliği ve yol değerleriyle yapılır. İstek X-Teamso-Mcp-Intent: read başlığıyla gider; Teamso veri değiştirecek bir isteği bu başlıkla reddeder (403).

{
  "name": "call_api_read",
  "arguments": {
    "id": "GET /expense-form/{id}",
    "path_params": {
      "id": "8f1c…"
    }
  }
}

Yazma araçları önce önizleme döndürür: gönderilecek isteği, şema kontrolünün sonucunu, silme ve SMS uyarılarını ve tek satırlık bir özeti. Bu aşamada Teamso'ya hiçbir şey gönderilmez; şemaya uymayan bir istek confirm: true ile de gönderilmez.

{
  "name": "call_api_write",
  "arguments": {
    "id": "POST /demand",
    "body": {
      "demandTypeId": "3b7e…",
      "message": "Yeni monitör talebi"
    }
  }
}

{
  "structuredContent": {
    "mode": "preview",
    "endpoint": {
      "id": "POST /demand",
      "module": "DEMAND",
      "sideEffect": "write",
      "smsCodeRequired": "never"
    },
    "request": {
      "method": "POST",
      "path": "/demand"
    },
    "summary": "Changes data: POST /demand — Create a request",
    "validation": {
      "checked": true,
      "valid": true,
      "errors": []
    },
    "nextAction": {
      "tool": "call_api_write",
      "arguments": {
        "id": "POST /demand",
        "body": {
          "demandTypeId": "3b7e…",
          "message": "Yeni monitör talebi"
        },
        "confirm": true
      },
      "reason": "Only after the user explicitly confirms this preview."
    }
  },
  "content": [
    {
      "type": "text",
      "text": "## Preview — nothing has been sent\n\n**Changes data: POST /demand — Create a request**\n…"
    }
  ]
}

Siz onayladıktan sonra asistan aynı çağrıyı confirm: true ile tekrarlar. SMS kodu isteyen işlemlerde önce request_sms_code ile kod gönderir, kodu size sorar ve otp_code olarak ekler:

{
  "name": "call_api_write",
  "arguments": {
    "id": "POST /expense-form/{expenseFormId}/finalize",
    "path_params": {
      "expenseFormId": "8f1c…"
    },
    "confirm": true,
    "otp_code": "123456"
  }
}

Örnek yanıt; alanlar araca göre değişir.

Güvenlik kuralları

• Yalnız katalogdaki uç kimlikleri çağrılır; serbest adres yoktur. Giriş, token, şifre ve güvenlik ayarı uçları kimseye listelenmez.
• Her istek token sahibinin Teamso yetkileriyle çalışır; ekranda yapamadığınız işlemi asistan da yapamaz. Yetkisiz bir istek API'de 403 ile reddedilir.
• Değişiklikler önizleme ve açık onay olmadan çalışmaz; silme işlemleri önizlemede ayrıca uyarılır.
• SMS kodu isteyen işlemler (ör. masraf formunu kesinleştirme) uygulamadaki gibi telefonunuza gelen kodla onaylanır.
• Dosya yanıtları 8 MB'a kadar gömülü dosya olarak gelir; yüklemeler base64 olarak, en çok 10 dosya ve toplam 10 MB.
• 40.000 karakteri aşan sonuçlar sığan kayıtlara kısaltılır ve truncated: true ile işaretlenir; hiçbir şey sessizce kesilmez.

Araç gruplarını seçme

Asistanınız daha az araç görsün istiyorsanız sunucu adresine ?toolsets= ekleyin (ya da X-Teamso-Toolsets başlığını gönderin). Yerel pakette aynı seçim TEAMSO_TOOLSETS ortam değişkeniyle yapılır. Varsayılan tüm araçlardır; bilinmeyen bir grup adı hata verir.

claude mcp add --transport http teamso https://mcp.teamso.com/v1?toolsets=core,leave,api --header "Authorization: Bearer tms_pat_..."

Gruplar: core, help, leave, approvals, employees, performance, communication, payroll, api

İstek ve yanıt sözleşmesi

Araçlar MCP tools/call ile çağrılır. Girdi JSON Schema 2020-12 ile doğrulanır; başarılı yanıt structuredContent (zincirleme için tipli veri) ve content (yalnız metin gösteren istemciler için kısa özet) içerir.

{
  "name": "calculate_leave_days",
  "arguments": {
    "leave_type_id": "6f1c…",
    "start": "2026-11-02",
    "end": "2026-11-04"
  }
}

Başka bir araçla devam etmek gerekiyorsa yanıt nextAction taşır: çağrılacak araç, argümanları ve nedeni. İzin akışı buna örnektir: calculate_leave_days → request_leave_otp → create_leave_request.

{
  "structuredContent": {
    "request": {
      "leaveTypeId": "6f1c…",
      "leaveTypeName": "Yıllık İzin",
      "start": "2026-11-02 09:00",
      "end": "2026-11-04 18:00",
      "workingDays": 3,
      "returnToWorkDate": "2026-11-05 09:00"
    },
    "remainingDays": 14,
    "remainingAfterRequest": 11,
    "canRequest": true,
    "problems": [],
    "nextAction": {
      "tool": "request_leave_otp",
      "arguments": {},
      "reason": "Creating the request needs an SMS code. After the user confirms these days, send the code, then call create_leave_request with the same leave_type_id, start, end and the otp_code."
    }
  },
  "content": [
    {
      "type": "text",
      "text": "## Yıllık İzin: 3 days\n\n- **Dates:** …\n- **Back at work:** 2026-11-05 09:00\n…"
    }
  ]
}

Örnek yanıt; alanlar araca göre değişir.

Hatalar isError: true ve ne yapılacağını söyleyen bir metinle döner; metnin sonunda Teamso API'nin HTTP durumu ve message_code değeri (ör. CREDIT_INSUFFICIENT, ITEM_NOT_FOUND) yer alır.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Your company does not have enough digital (SMS) credit for this step. Ask your Teamso administrator to top up credits.\n\n_Teamso API: HTTP 200 · `CREDIT_INSUFFICIENT`_"
    }
  ]
}

Tarihler: izinde yyyy-MM-dd HH:mm Türkiye saati (yalnız tarih verilirse başlangıç vardiya başı, bitiş vardiya sonu; varsayılan 09:00 ve 18:00), hedeflerde ve süzgeçlerde yyyy-MM-dd, bordro döneminde yyyy-MM ya da yyyy.

get_payslip_pdf pusulayı application/pdf türünde gömülü bir kaynak (base64) olarak döndürür.

Örnekler

Asistanınıza doğal dille sorun; araçları kendisi sırayla çağırır.

Nasıl çalışır?

1. Asistan aracı token'ınızla birlikte https://mcp.teamso.com/v1 adresine gönderir.
2. Sunucu isteği sizin adınıza Teamso API'sine iletir; yetkileriniz ve şirket kurallarınız (IP kısıtlaması, onay akışları, SMS onayı) aynen uygulanır.
3. Yanıt tipli veri ve kısa metin olarak asistana döner. Sunucu durumsuzdur: oturum ya da token saklanmaz.
4. Teamso'daki yeni yetki ve kurallar araçlara da hemen yansır; ek kurulum gerekmez.

Araç referansı

Her aracın parametreleri. Zorunlu olmayanlar boş bırakılabilir.

Sorun giderme

401 Unauthorized

Token yanlış, süresi dolmuş ya da iptal edilmiş. MCP erişimi sayfasından yeni token oluşturun; başlık Bearer tms_pat_... biçiminde olmalı.

403 ACCESS_DENIED

Bu işlem için yetkiniz yok ya da işlem token'la yapılamıyor (şifre, güvenlik ayarları, token ve entegrasyon anahtarı yönetimi).

403 IP_NOT_ALLOWED

Şirketinizin IP kısıtlaması isteği reddetti. Yerel pakette bilgisayarınızın IP adresi izinli olmalı.

CREDIT_INSUFFICIENT

İzin oluşturma ve iptal SMS ile dijital kredi harcar; şirket yöneticinizden kredi yüklemesini isteyin.

OTP_NOT_DONE

SMS kodu doğrulanmadı ya da 3 dakikalık süre doldu. request_leave_otp ile yeni kod isteyin.

429 Too Many Requests

Hosted sunucu token başına dakikalık istek sınırı uygular; yanıttaki Retry-After süresi kadar bekleyip yeniden deneyin.

Uç bulunamıyor

find_api_endpoints bir işlemi bulamıyorsa ya da describe_api_endpoint "not found" diyorsa token sahibinin o işlem için yetkisi yoktur ya da uç MCP'ye kapalıdır (giriş, token, şifre). Yetki şirket yöneticinizden istenir; yeni yetki hemen yansır.

Araçlar görünmüyor

İstemciyi tamamen yeniden başlatın; yerel pakette Node.js 20+ ve sabit sürüm kullandığınızdan emin olun.

Sık sorulan sorular