OSIR Domain Registrar

OSIR Agent Platform

AI integration servers for the OSIR 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:

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

In Claude, open Settings → Connectors → Add custom connector, then pick one of two setups:

For Option B, don't pick "Use Claude's published identity" or "Register automatically". OSIR doesn't support either one.

Option A: 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: /mcp/oauth always requires OAuth: it returns 401 with an RFC 9728 challenge. The URL-only /mcp/http needs MCP_OAUTH_CHALLENGE_ENABLED=false. If you leave that at its default (true), every MCP path requires OAuth. Session lifetimes are tunable via MCP_SESSION_IDLE_MINUTES and MCP_SESSION_MAX_HOURS.

What your assistant can do

Running the servers yourself

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

# 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. 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):

{
  "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

# 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.

Tools

106 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 - Stage a change of the payment term (billing cycle) for a VPS instance; confirm with executeConfirmedAction.
• 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 - Stage removal of an SSH key from your account; confirm with executeConfirmedAction.
• deleteVpsInstance - Stage deletion/cancellation of a VPS instance.

Build, test, deploy

./gradlew build        # build all modules + run tests
./gradlew test         # tests only

docker-compose up -d   # run both servers in containers

The provided docker-compose.yml, build-and-deploy.bat, and the CI workflow reference a placeholder container registry (registry.example.com) — point them at your own. See DEPLOYMENT.md for the production checklist (PostgreSQL, TLS, scaling).

Configuration

All settings are environment variables with sensible defaults — nothing secret is committed.

See .env.example for the full list.

Project layout

common/      Shared library — 12 services, 9 REST clients, ~174 models
mcp-server/  Quarkus MCP server — 106 tools, 11 prompts, 2 resources
a2a-server/  Quarkus A2A server — 9 agents, 89 skills, JSON-RPC, JPA task persistence

Both servers depend on common, so a backend operation is implemented once and exposed two ways.

Documentation

• GUIDE.md — complete usage guide, tool reference, walkthroughs
• WEBSITE-DESIGN.md — AI website design: customer guide, use cases, frontend integration
• DEVELOPING.md — repo layout, build/run commands, architecture notes
• VPS-OS-BUILD.md — ordering a VPS with an OS, SSH keys, reinstall, and the OSIR APP DEPLOY flow. Read this before touching the VPS tools: ordering and building are two separate VirtFusion steps, and orderVps alone hands over a server with no operating system.
• A2A-API-REFERENCE.md — A2A protocol spec (methods, errors, agents)
• A2A-ARCHITECTURE.md — A2A design document
• A2A-CONFIRMATION-GATE-SPEC.md — staging destructive ops behind executeConfirmedAction
• DEPLOYMENT.md — production deployment checklist

License

Apache License 2.0.