mcp-a2a

# OSIR Agent Platform

AI integration servers for the [OSIR](https://osir.com) domain registrar. Connect Claude, ChatGPT,
or any AI assistant to real domain, DNS, VPS, billing, and account operations — either as
individual tools (MCP) or as task-solving specialist agents (A2A).

Two servers, one shared backend client library:

| Server | Port | Protocol | What it gives an AI |
|--------|------|----------|---------------------|
| **MCP Server** | 8081 | [Model Context Protocol](https://modelcontextprotocol.io) (SSE + Streamable HTTP) | 103 fine-grained tools (`checkDomainAvailability`, `registerDomain`, `createDnsRecord`, `createMailbox`, `osirSitePublish`, …) + 11 guided prompts |
| **A2A Server** | 8082 | [Google Agent-to-Agent](https://google.github.io/A2A/) (JSON-RPC 2.0) | 7 specialist agents with 50+ skills and an orchestrator for multi-step workflows |

Use **MCP** when one assistant should call individual operations. Use **A2A** when you want to hand
a whole task ("set up example.com with DNS and check my balance") to agents that coordinate the work.

---

## What is MCP?

MCP (Model Context Protocol) is an open standard that connects AI assistants to external tools and
data. An MCP server publishes a set of callable tools; any MCP client — Claude Desktop, Cursor,
Copilot, or a custom agent — can discover and invoke them. OSIR implements an MCP server
purpose-built for domain and infrastructure management, which is what makes it an AI-native
registrar rather than a traditional one with a chat box bolted on.

## Connect OSIR to Claude

Add OSIR as a custom connector from your Claude settings — just the URL, no OAuth fields, no
config file, no install:

1. In Claude, open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Set **Name** to `OSIR`.
4. Set the **Remote MCP server URL** to `https://be.osir.com/mcp/http`.
5. Save. Leave the Advanced settings (OAuth Client ID / Secret) empty.

```
Claude · Add custom connector

Name:                OSIR
Remote MCP server:   https://be.osir.com/mcp/http
```

**Signing in happens inside the conversation.** The first time your assistant needs an
authenticated tool, it starts a device login: you get a link to `auth.osir.com` and a short code,
you approve in your browser, and the assistant continues with a session scoped to that
conversation. Sessions are deliberately short-lived (they expire after ~30 minutes of inactivity,
8 hours maximum) and end instantly when you say "log me out" — so a connected chat never holds
standing access to your domains, servers, and billing.

The same URL works in any MCP client that supports a remote (streamable HTTP) server and can
drive the in-chat device login.

> **Self-hosting note:** URL-only connectors require `MCP_OAUTH_CHALLENGE_ENABLED=false` on the
> MCP server. Leaving the challenge enabled (the default) switches the server to OAuth mode
> instead: it answers unauthenticated requests with a `401` + RFC 9728 challenge and clients
> authenticate against your identity provider with a pre-registered client id. Session lifetimes
> are tunable via `MCP_SESSION_IDLE_MINUTES` and `MCP_SESSION_MAX_HOURS`.

### What your assistant can do

| Capability | Example request |
|------------|-----------------|
| Search availability | "Is coolstartup.io available, and what does it cost?" |
| Register a domain | "Register it for two years with WHOIS privacy." |
| Manage DNS | "Point it at 192.0.2.10 and add my email records." |
| Renew and transfer | "Renew everything expiring in the next 30 days." |
| Provision a VPS | "Spin up a 2 vCPU server in Frankfurt running Ubuntu." |
| Host email | "Enable email on example.com and create info@ with a 10 GB mailbox." |

---

## Running the servers yourself

Want to host your own instance or develop against the code? Requires **Java 21**; Gradle is bundled
via the wrapper.

```bash
# Run the MCP server (port 8081)
./gradlew :mcp-server:quarkusDev

# Run the A2A server (port 8082)
./gradlew :a2a-server:quarkusDev
```

Copy `.env.example` to `.env` and adjust if you're pointing at your own backend/KeyCloak/Ollama.
Everything defaults to the public OSIR endpoints, so the servers run out of the box.

### Connect an MCP client (Claude Desktop / Claude Code)

Add to your client's MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "osir": { "url": "http://localhost:8081/mcp/sse" }
  }
}
```

Restart the client and the OSIR tools appear. Then just ask:

> "Is pizzashqip.al available? If not, suggest alternatives."
> "List all my domains and show which expire in the next 30 days."
> "Add an A record pointing example.al to 203.0.113.10 and a CNAME for www."

Most operations need authentication — ask the assistant to *"log me in to OSIR using the device
flow"* and it walks you through browser-based OAuth (KeyCloak, RFC 8628).

### Call the A2A server

```bash
# Discover the agents
curl http://localhost:8082/.well-known/agents | jq '.[].name'

# Send a task (the platform routes it to the right specialist)
curl -X POST http://localhost:8082/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0", "id": "1", "method": "tasks/send",
    "params": { "message": { "role": "user",
      "parts": [{"type": "text", "text": "Check if example.com is available"}] } }
  }'
```

Tasks stream over `POST /a2a/stream` (SSE), support multi-turn `input-required` flows, and the
orchestrator decomposes complex requests across agents (max 15 steps).

---

## What you can do

**Domains** — availability, registration, renewal, transfer, lock/unlock, auto-renew, WHOIS
privacy, nameservers, AI-powered name suggestions.
**DNS** — list/create/update/delete records.
**VPS** — browse packages and locations, order, manage, panel login.
**Billing** — balance, invoices, payments, fee previews, domain pricing.
**Contacts**, **Transfers**, **Hosts**, **Audit logs**, **Account** profile & summary.

Full tool/skill catalog, example conversations, and end-to-end walkthroughs are in **[GUIDE.md](docs/GUIDE.md)**.

## Tools

105 tools, verified against the live server (tools/list on https://be.osir.com/mcp/http).

- **addPrefixToDomain** - Generate domain suggestions by adding prefixes.
- **addSshKey** - Store an SSH public key on your account so it can be injected into VPS installs.
- **addSuffixToDomain** - Generate domain suggestions by adding suffixes.
- **buildVpsInstance** - Stage an operating system install on a VPS instance.
- **bulkDomainSuggestions** - Generate domain name suggestions for one or more keywords across a chosen set of TLDs.
- **cancelTransfer** - Stage cancellation of a pending domain transfer.
- **changeVpsPaymentTerm** - Change the payment term (billing cycle) for a VPS instance.
- **checkDeviceLoginStatus** - Poll for device login completion.
- **checkDomainAvailability** - Check if a domain name is available for registration, with price.
- **checkHostAvailability** - Check if a host/glue record name is available for creation.
- **checkKeywordAvailability** - Check keyword availability across all supported TLDs and registries with detailed results.
- **checkKeywordAvailabilitySummary** - Check keyword availability summary statistics without detailed domain results (faster).
- **countMyVpsInstances** - Get the total count of VPS instances owned by the authenticated user.
- **createAccount** - Create a new OSIR customer account.
- **createContact** - Create a new contact for use with domain registrations.
- **createDnsRecord** - Create a new DNS record for a domain.
- **createHost** - Create a new host/glue record (e.g., for custom nameservers).
- **createMailbox** - Stage creation of a paid mailbox on a mail-enabled domain.
- **createPaymentSession** - Stage creation of a Stripe payment checkout session to add funds to account balance.
- **deleteContact** - Stage deletion of a contact.
- **deleteDnsRecord** - Stage deletion of a DNS record.
- **deleteHost** - Stage deletion of a host/glue record.
- **deleteMailbox** - Stage deletion of a mailbox.
- **deleteSshKey** - Remove an SSH key from your account.
- **deleteVpsInstance** - Stage deletion/cancellation of a VPS instance.
- **enableMailDomain** - Enable email hosting on a domain you own.
- **executeConfirmedAction** - Execute a previously staged destructive or financial action after user approval.
- **generateDomainSuggestions** - Generate domain name suggestions based on keywords.
- **getAccountBalance** - Get the current account balance for the authenticated user.
- **getAccountSummary** - Get a comprehensive summary of the user's account: profile, balance, domain count, VPS count, and pending transfers.
- **getAuthStatus** - Check whether the current session is authenticated.
- **getContact** - Get detailed information about a specific contact.
- **getContactsForDomain** - Get all contacts (registrant, admin, tech, billing) assigned to a domain.
- **getDedicatedServerCatalog** - Get all available dedicated server configurations with pricing and specifications.
- **getDnsRecord** - Get details of a specific DNS record.
- **getDomainAuditTrail** - Get the audit trail (history of all changes) for a specific domain.
- **getDomainExtensions** - Get all available domain extensions (TLDs) with pricing information.
- **getDomainInfo** - Get detailed information about a domain including expiration date, nameservers, and status.
- **getDomainPricing** - Get pricing for domain extensions from the product catalog.
- **getHostingBundle** - Get the hosting options and exact prices for a specific domain: recommended VPS packages (cheapest first), email plans, web forwarding, and app/site deployment (builds are free; going live runs on a VPS).
- **getHostsForDomain** - List all host/glue records associated with a domain.
- **getInvoiceDetails** - Get detailed information about a specific invoice including line items.
- **getInvoiceStatistics** - Get summary statistics of invoices: to