# invitation.az — MCP & AI Agent Integration Guide

> **How to connect AI assistants (Claude, ChatGPT, Cursor, etc.) to invitation.az**
> This document is for developers and platform clients who want to give their AI tools direct access to the invitation.az platform.

---

## What is MCP?

**MCP (Model Context Protocol)** is an open standard that lets AI assistants (Claude, Cursor, Windsurf, and others) connect to external services and call their APIs directly — without copy-pasting data or switching context.

By connecting to invitation.az MCP, your AI can:
- ✅ Create digital invitations
- ✅ Fetch guest RSVP lists
- ✅ Check venue booking availability
- ✅ Manage event details

---

## 1. Auto-Discovery (Recommended)

Most MCP clients support automatic discovery. Simply point them at:

```
https://invitation.az/.well-known/mcp/server-card.json
```

The server card contains all endpoints, capabilities, and auth info.

---

## 2. Manual MCP Configuration

### For Claude Desktop (`claude_desktop_config.json`)

Add to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "invitation-az": {
      "type": "streamable_http",
      "url": "https://invitation.az/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

**Config file location:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

### For Cursor / Windsurf / Continue

In your MCP settings panel, add:

```
Server URL: https://invitation.az/api/mcp
Transport: Streamable HTTP
Auth: Bearer Token
```

### For SSE-based clients

```
SSE Endpoint: https://invitation.az/api/mcp/sse
```

---

## 3. Authentication

Get your API token from your **invitation.az** dashboard → **Settings → API Keys**.

Then include it in every request:

```http
Authorization: Bearer <your_token>
```

**OAuth 2.0** is also supported:
- **Token endpoint:** `https://invitation.az/api/auth/login`
- **User info:** `https://invitation.az/api/auth/me`
- **Scopes:** `invitations:read`, `invitations:write`, `guests:read`, `guests:write`
- **Full OAuth config:** `https://invitation.az/.well-known/openid-configuration`

---

## 4. Available MCP Tools

| Tool | Description |
|------|-------------|
| `create_invitation` | Create and customize a digital event invitation |
| `get_guest_rsvps` | Fetch guest list and real-time RSVP responses |
| `check_booking_availability` | Check availability calendar for dates and venues |

---

## 5. OpenAPI / Swagger (for developers)

Full REST API documentation:

| Resource | URL |
|----------|-----|
| Swagger UI | `https://invitation.az/api/documentation` |
| OpenAPI JSON | `https://invitation.az/openapi.json` |
| OpenAPI JSON (alt) | `https://invitation.az/docs/api-docs.json` |

---

## 6. Agent Discovery Endpoints

For AI platforms doing automated discovery:

| Endpoint | Purpose |
|----------|---------|
| `/.well-known/mcp/server-card.json` | MCP Server Card (SEP-1649) |
| `/.well-known/agent-card.json` | A2A Agent Card |
| `/.well-known/openid-configuration` | OpenID Connect metadata |
| `/.well-known/jwks.json` | JSON Web Key Set (HS256) |
| `/.well-known/oauth-authorization-server` | OAuth AS metadata |
| `/.well-known/oauth-protected-resource` | OAuth resource metadata |
| `/.well-known/acp.json` | Agentic Commerce Protocol |
| `/llms.txt` | LLM context (Azerbaijani) |
| `/ai.txt` | AI platform metadata |
| `/robots.txt` | Crawler rules (includes MCP discovery comments) |

---

## 7. Pricing (AZN — KapitalBank)

| Package | Type | Price |
|---------|------|-------|
| Basic (Fərdi) | Invitation | 29 AZN |
| VIP (Fərdi) | Invitation | 59 AZN |
| Premium (Fərdi) | Invitation | 99 AZN |
| Sifariş ilə | Custom Design | 99+ AZN |
| Basic (Biznes) | Business | 109 AZN/year |
| VIP (Biznes) | Business | 159 AZN/year |
| Premium (Biznes) | Business | 229 AZN/year |
| Sayt (Fərdi) | Website | 19 AZN + 7 AZN/month |
| Sayt (Biznes) | Website | 60 AZN + 10 AZN/month |

**Payment method:** KapitalBank (3D Secure, Visa/Mastercard)

---

## 8. DNS-AID Records (DNS-based agent discovery)

The platform publishes DNS AI Discovery records for validating resolvers:

```
_index._agents.invitation.az  SVCB  1 invitation.az alpn="mcp" endpoint="/api/mcp"
_a2a._agents.invitation.az    SVCB  1 invitation.az alpn="a2a" endpoint="/.well-known/agent-card.json"
```

**DNSSEC:** Signed — Algorithm 13 (ECDSA P-256), Key Tag 2371, SHA-256 Digest.

---

## 9. Quick Test

Verify the MCP endpoint is live:

```bash
curl https://invitation.az/api/mcp
```

Expected response:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "Devetname MCP Server", "version": "1.0.0" },
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true }
    },
    "instructions": "Devetname event platform MCP server. Use tools to create invitations, track RSVPs, and check booking availability."
  }
}
```

---

## Support

- **Platform:** https://invitation.az
- **API Docs:** https://invitation.az/api/documentation
- **MCP Discovery:** https://invitation.az/.well-known/mcp/server-card.json

---

*Last updated: 2026-08-09*