{
  "markdown": "# OSIR Agent Platform\n\nAI integration servers for the [OSIR](https://osir.com) domain registrar. Connect Claude, ChatGPT,\nor any AI assistant to real domain, DNS, VPS, billing, and account operations — either as\nindividual tools (MCP) or as task-solving specialist agents (A2A).\n\nTwo servers, one shared backend client library:\n\n| Server | Port | Protocol | What it gives an AI |\n|--------|------|----------|---------------------|\n| **MCP Server** | 8081 | [Model Context Protocol](https://modelcontextprotocol.io) (SSE + Streamable HTTP) | 103 fine-grained tools (`checkDomainAvailability`, `registerDomain`, `createDnsRecord`, `createMailbox`, `osirSitePublish`, …) + 11 guided prompts |\n| **A2A Server** | 8082 | [Google Agent-to-Agent](https://google.github.io/A2A/) (JSON-RPC 2.0) | 9 specialist agents with 89 skills and an orchestrator for multi-step workflows |\n\nUse **MCP** when one assistant should call individual operations. Use **A2A** when you want to hand\na whole task (\"set up example.com with DNS and check my balance\") to agents that coordinate the work.\n\n---\n\n## What is MCP?\n\nMCP (Model Context Protocol) is an open standard that connects AI assistants to external tools and\ndata. An MCP server publishes a set of callable tools; any MCP client — Claude Desktop, Cursor,\nCopilot, or a custom agent — can discover and invoke them. OSIR implements an MCP server\npurpose-built for domain and infrastructure management, which is what makes it an AI-native\nregistrar rather than a traditional one with a chat box bolted on.\n\n## Connect OSIR to Claude\n\nAdd OSIR as a custom connector from your Claude settings — just the URL, no OAuth fields, no\nconfig file, no install:\n\n1. In Claude, open **Settings → Connectors**.\n2. Click **Add custom connector**.\n3. Set **Name** to `OSIR`.\n4. Set the **Remote MCP server URL** to `https://be.osir.com/mcp/http`.\n5. Save. Leave the Advanced settings (OAuth Client ID / Secret) empty.\n\n```\nClaude · Add custom connector\n\nName:                OSIR\nRemote MCP server:   https://be.osir.com/mcp/http\n```\n\n**Signing in happens inside the conversation.** The first time your assistant needs an\nauthenticated tool, it starts a device login: you get a link to `auth.osir.com` and a short code,\nyou approve in your browser, and the assistant continues with a session scoped to that\nconversation. Sessions are deliberately short-lived (they expire after ~30 minutes of inactivity,\n8 hours maximum) and end instantly when you say \"log me out\" — so a connected chat never holds\nstanding access to your domains, servers, and billing.\n\nThe same URL works in any MCP client that supports a remote (streamable HTTP) server and can\ndrive the in-chat device login.\n\n> **Self-hosting note:** URL-only connectors require `MCP_OAUTH_CHALLENGE_ENABLED=false` on the\n> MCP server. Leaving the challenge enabled (the default) switches the server to OAuth mode\n> instead: it answers unauthenticated requests with a `401` + RFC 9728 challenge and clients\n> authenticate against your identity provider with a pre-registered client id. Session lifetimes\n> are tunable via `MCP_SESSION_IDLE_MINUTES` and `MCP_SESSION_MAX_HOURS`.\n\n### What your assistant can do\n\n| Capability | Example request |\n|------------|-----------------|\n| Search availability | \"Is coolstartup.io available, and what does it cost?\" |\n| Register a domain | \"Register it for two years with WHOIS privacy.\" |\n| Manage DNS | \"Point it at 192.0.2.10 and add my email records.\" |\n| Renew and transfer | \"Renew everything expiring in the next 30 days.\" |\n| Provision a VPS | \"Spin up a 2 vCPU server in Frankfurt running Ubuntu.\" |\n| Host email | \"Enable email on example.com and create info@ with a 10 GB mailbox.\" |\n\n---\n\n## Running the servers yourself\n\nWant to host your own instance or develop against the code? Requires **Java 21**; Gradle is bundled\nvia the wrapper.\n\n```bash\n# Run the MCP server (port 8081)\n./gradlew :mcp-server:quarkusDev\n\n# Run the A2A server (port 8082)\n./gradlew :a2a-server:quarkusDev\n```\n\nCopy `.env.example` to `.env` and adjust if you're pointing at your own backend/KeyCloak/Ollama.\nEverything defaults to the public OSIR endpoints, so the servers run out of the box.\n\n### Connect an MCP client (Claude Desktop / Claude Code)\n\nAdd to your client's MCP config (e.g. `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"osir\": { \"url\": \"http://localhost:8081/mcp/sse\" }\n  }\n}\n```\n\nRestart the client and the OSIR tools appear. Then just ask:\n\n> \"Is pizzashqip.al available? If not, suggest alternatives.\"\n> \"List all my domains and show which expire in the next 30 days.\"\n> \"Add an A record pointing example.al to 203.0.113.10 and a CNAME for www.\"\n\nMost operations need authentication — ask the assistant to *\"log me in to OSIR using the device\nflow\"* and it walks you through browser-based OAuth (KeyCloak, RFC 8628).\n\n### Call the A2A server\n\n```bash\n# Discover the agents\ncurl http://localhost:8082/.well-known/agents | jq '.[].name'\n\n# Send a task (the platform routes it to the right specialist)\ncurl -X POST http://localhost:8082/a2a \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\", \"id\": \"1\", \"method\": \"tasks/send\",\n    \"params\": { \"message\": { \"role\": \"user\",\n      \"parts\": [{\"type\": \"text\", \"text\": \"Check if example.com is available\"}] } }\n  }'\n```\n\nTasks stream over `POST /a2a/stream` (SSE), support multi-turn `input-required` flows, and the\norchestrator decomposes complex requests across agents (max 15 steps).\n\n---\n\n## What you can do\n\n**Domains** — availability, registration, renewal, transfer, lock/unlock, auto-renew, WHOIS\nprivacy, nameservers, AI-powered name suggestions.\n**DNS** — list/create/update/delete records.\n**VPS** — browse packages and locations, order, manage, panel login.\n**Billing** — balance, invoices, payments, fee previews, domain pricing.\n**Contacts**, **Transfers**, **Hosts**, **Audit logs**, **Account** profile & summary.\n\nFull tool/skill catalog, example conversations, and end-to-end walkthroughs are in **[GUIDE.md](docs/GUIDE.md)**.\n\n## Tools\n\n105 tools, verified against the live server (tools/list on https://be.osir.com/mcp/http).\n\n- **addPrefixToDomain** - Generate domain suggestions by adding prefixes.\n- **addSshKey** - Store an SSH public key on your account so it can be injected into VPS installs.\n- **addSuffixToDomain** - Generate domain suggestions by adding suffixes.\n- **buildVpsInstance** - Stage an operating system install on a VPS instance.\n- **bulkDomainSuggestions** - Generate domain name suggestions for one or more keywords across a chosen set of TLDs.\n- **cancelTransfer** - Stage cancellation of a pending domain transfer.\n- **changeVpsPaymentTerm** - Change the payment term (billing cycle) for a VPS instance.\n- **checkDeviceLoginStatus** - Poll for device login completion.\n- **checkDomainAvailability** - Check if a domain name is available for registration, with price.\n- **checkHostAvailability** - Check if a host/glue record name is available for creation.\n- **checkKeywordAvailability** - Check keyword availability across all supported TLDs and registries with detailed results.\n- **checkKeywordAvailabilitySummary** - Check keyword availability summary statistics without detailed domain results (faster).\n- **countMyVpsInstances** - Get the total count of VPS instances owned by the authenticated user.\n- **createAccount** - Create a new OSIR customer account.\n- **createContact** - Create a new contact for use with domain registrations.\n- **createDnsRecord** - Create a new DNS record for a domain.\n- **createHost** - Create a new host/glue record (e.g., for custom nameservers).\n- **createMailbox** - Stage creation of a paid mailbox on a mail-enabled domain.\n- **createPaymentSession** - Stage creation of a Stripe payment checkout session to add funds to account balance.\n- **deleteContact** - Stage deletion of a contact.\n- **deleteDnsRecord** - Stage deletion of a DNS record.\n- **deleteHost** - Stage deletion of a host/glue record.\n- **deleteMailbox** - Stage deletion of a mailbox.\n- **deleteSshKey** - Remove an SSH key from your account.\n- **deleteVpsInstance** - Stage deletion/cancellation of a VPS instance.\n- **enableMailDomain** - Enable email hosting on a domain you own.\n- **executeConfirmedAction** - Execute a previously staged destructive or financial action after user approval.\n- **generateDomainSuggestions** - Generate domain name suggestions based on keywords.\n- **getAccountBalance** - Get the current account balance for the authenticated user.\n- **getAccountSummary** - Get a comprehensive summary of the user's account: profile, balance, domain count, VPS count, and pending transfers.\n- **getAuthStatus** - Check whether the current session is authenticated.\n- **getContact** - Get detailed information about a specific contact.\n- **getContactsForDomain** - Get all contacts (registrant, admin, tech, billing) assigned to a domain.\n- **getDedicatedServerCatalog** - Get all available dedicated server configurations with pricing and specifications.\n- **getDnsRecord** - Get details of a specific DNS record.\n- **getDomainAuditTrail** - Get the audit trail (history of all changes) for a specific domain.\n- **getDomainExtensions** - Get all available domain extensions (TLDs) with pricing information.\n- **getDomainInfo** - Get detailed information about a domain including expiration date, nameservers, and status.\n- **getDomainPricing** - Get pricing for domain extensions from the product catalog.\n- **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).\n- **getHostsForDomain** - List all host/glue records associated with a domain.\n- **getInvoiceDetails** - Get detailed information about a specific invoice including line items.\n- **getInvoiceStatistics** - Get summary statistics of invoices: total paid, pending, overdue amounts.\n- **getMailboxQuote** - Get a display-only price quote for a mailbox plan.\n- **getMailboxUsage** - Get disk usage per mailbox in bytes, for quota display alongside the plan's quotaBytes.\n- **getMailDnsRecords** - Get the DNS records a mail domain needs (MX, SPF, DKIM, ...) - for customers managing DNS externally.\n- **getMyAuditLogs** - Get recent audit logs for the authenticated user across all services.\n- **getMyProfile** - Get the authenticated user's profile and account information including name, email, organization, balance, and domain/VPS counts.\n- **getPaymentTransactions** - Get payment transaction history for the authenticated user.\n- **getProductCatalog** - Get the complete product catalog including domain extensions, VPS packages, and dedicated servers.\n- **getRecentActivity** - Get the most recent activity across all domains and services for the user.\n- **getTransferQuote** - Get a transfer price quote for a domain.\n- **getTransferStatus** - Check the current status of a domain transfer.\n- **getVpsInstanceDetails** - Get detailed information about a specific VPS instance including resource usage.\n- **getVpsPackageDetails** - Get detailed information about a specific VPS package including all pricing tiers.\n- **initializeDnsZone** - Initialize (create) the DNS zone for a domain.\n- **initiateTransfer** - Stage initiation of a domain transfer from another registrar.\n- **listCategorizedTlds** - List TLDs from the OSIR catalog that have category and audience metadata populated.\n- **listContacts** - List all contacts for the authenticated user with optional search.\n- **listDnsRecords** - List all DNS records for a domain.\n- **listInvoices** - List invoices for the authenticated user with optional status filtering and pagination.\n- **listMailboxes** - List your mailboxes with plan, payment term, status, and next renewal date.\n- **listMailDomains** - List your domains that are enabled for email hosting, with status (PENDING_DNS or ACTIVE) and DNS mode.\n- **listMailPlans** - List available email mailbox plans with quotas and prices (monthly and annual, in cents).\n- **listMySshKeys** - List the SSH keys stored on your account, with their ids and SHA256 fingerprints.\n- **listMyVpsInstances** - List all VPS instances owned by the authenticated user.\n- **listPendingTransfers** - List all pending incoming (gaining) domain transfers.\n- **listUserDomains** - List all domains owned by the authenticated user.\n- **listVpsLocations** - List available VPS hosting locations (cities/countries) with available packages.\n- **listVpsOsTemplates** - List operating system templates available to install.\n- **listVpsPackages** - List available VPS hosting packages with pricing, specs, and locations.\n- **lockDomain** - Enable registrar lock on a domain to prevent unauthorized transfers.\n- **loginToVpsPanel** - Generate a one-time login URL to the VPS control panel (VirtFusion) for managing the server.\n- **loginWithDevice** - Start a device authorization login (RFC 8628).\n- **logout** - Log out: revokes the session's tokens at the identity provider immediately.\n- **orderVps** - Stage an order for a new VPS instance.\n- **osirAppCreateUpload** - Create an upload ticket for deploying app source code to Osir.\n- **osirAppDelete** - Stage deletion of an Osir app.\n- **osirAppDeploy** - Deploy an app to Osir (free tier) and get a live HTTPS URL; the app runs isolated in a microVM.\n- **osirAppGetSource** - Get a short-lived signed download URL for an Osir app's current source zip - use this to make edits to a deployed app without the user re-attaching the project: download, patch the files, then osirAppCreateUpload (PUT the new zip) and osirAppDeploy under the SAME name; the platform rebuilds and, for owned-tier apps, auto-ships the new version to the user's box.\n- **osirAppList** - List the authenticated user's deployed Osir apps with their live URLs and status.\n- **osirAppLogs** - Get recent logs from an Osir app's microVM ('why is my app broken?').\n- **osirAppMoveToOwned** - Move a deployed Osir app from the shared free tier onto a VPS the user owns: attach one they already have (instanceId, spends nothing) or order one (packageId, gated).\n- **osirAppProvisionDatabase** - Provision a managed Postgres database for an Osir app.\n- **osirAppSetSecret** - Set an environment secret for an Osir app (e.g.\n- **osirAppStatus** - Get an Osir app's current status, live URL, and health ('is my app working?').\n- **osirSiteDesignBrief** - Step 1 of designing a website with OSIR.\n- **osirSitePublish** - Publish a single-page website to a live HTTPS URL on Osir (free tier) - ANY complete HTML document works: the user's own site, a page designed in this chat, or one from the osirSiteDesignBrief flow.\n- **payInvoice** - Stage payment of an outstanding invoice from account balance.\n- **previewPaymentFees** - Preview the fees that would be charged for a given payment amount.\n- **registerDomain** - Stage registration of a new domain name.\n- **renewDomain** - Stage renewal of a domain for a specified number of years.\n- **setMailboxPassword** - Set a new password on a mailbox.\n- **spinDomainWords** - Generate domain suggestions by spinning/replacing words.\n- **suggestAlternatives** - Suggest alternative domain names if the requested one is unavailable (legacy method).\n- **transferDomain** - Stage transfer of a domain from another registrar to OSIR.\n- **unlockDomain** - Stage removal of registrar lock from a domain to allow transfers.\n- **updateContact** - Update an existing contact's information.\n- **updateDnsRecord** - Update an existing DNS record.\n- **updateDomainAutoRenew** - Enable or disable auto-renewal for a domain.\n- **updateDomainPrivacy** - Enable or disable WHOIS privacy protection for a domain.\n- **updateNameservers** - Update nameservers for a domain.\n- **validateDomainName** - Validate if a domain name format is correct.\n- **verifyAccount** - Verify a newly created OSIR account with the code from the verification email - step 2 of onboarding, no authentication required.\n- **verifyMailDns** - Check that a mail domain's DNS records resolve; activates the domain for email when all records are found.\n\n\n---\n\n## Build, test, deploy\n\n```bash\n./gradlew build        # build all modules + run tests\n./gradlew test         # tests only\n\ndocker-compose up -d   # run both servers in containers\n```\n\nThe provided `docker-compose.yml`, `build-and-deploy.bat`, and the CI workflow reference a\nplaceholder container registry (`registry.example.com`) — point them at your own.\nSee **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** for the production checklist (PostgreSQL, TLS, scaling).\n\n## Configuration\n\nAll settings are environment variables with sensible defaults — nothing secret is committed.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OSIR_BACKEND_URL` | `https://be.osir.com` | Backend API |\n| `KEYCLOAK_URL` | `https://auth.osir.com` | KeyCloak auth server |\n| `KEYCLOAK_REALM` | `osir` | KeyCloak realm |\n| `KEYCLOAK_CLIENT_ID` | `osir-cli` | OAuth client ID |\n| `OLLAMA_URL` | `http://localhost:11434` | Ollama LLM (MCP chat UI) |\n| `CORS_ORIGINS` | `https://osir.com,…` | Allowed CORS origins |\n| `A2A_SIGNING_SECRET` | *(empty)* | Optional HMAC-SHA256 request signing |\n\nSee [`.env.example`](.env.example) for the full list.\n\n## Project layout\n\n```\ncommon/      Shared library — 12 services, 9 REST clients, ~174 models\nmcp-server/  Quarkus MCP server — 105 tools, 11 prompts, 2 resources, chat UI\na2a-server/  Quarkus A2A server — 9 agents, 89 skills, JSON-RPC, JPA task persistence\n```\n\nBoth servers depend on `common`, so a backend operation is implemented once and exposed two ways.\n\n## Documentation\n\n- **[GUIDE.md](docs/GUIDE.md)** — complete usage guide, tool reference, walkthroughs\n- **[WEBSITE-DESIGN.md](docs/WEBSITE-DESIGN.md)** — AI website design: customer guide, use cases, frontend integration\n- **[DEVELOPING.md](docs/DEVELOPING.md)** — repo layout, build/run commands, architecture notes\n- **[VPS-OS-BUILD.md](docs/VPS-OS-BUILD.md)** — ordering a VPS **with an OS**, SSH keys, reinstall, and\n  the OSIR APP DEPLOY flow. Read this before touching the VPS tools: ordering and building are two\n  separate VirtFusion steps, and `orderVps` alone hands over a server with no operating system.\n- **[A2A-API-REFERENCE.md](docs/A2A-API-REFERENCE.md)** — A2A protocol spec (methods, errors, agents)\n- **[A2A-ARCHITECTURE.md](docs/A2A-ARCHITECTURE.md)** — A2A design document\n- **[A2A-CONFIRMATION-GATE-SPEC.md](docs/A2A-CONFIRMATION-GATE-SPEC.md)** — staging destructive ops\n  behind `executeConfirmedAction`\n- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** — production deployment checklist\n\n## License\n\n[Apache License 2.0](LICENSE).\n",
  "bytes": 18777,
  "sha": "64a2d035c0a25e22cf1f5861df845d17720195ffbc5f48da7e9fc1c6cf17f539",
  "repo_slug": "osir-inc/mcp-a2a",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_osir_domain_registrar_9dc98dc2/readme"
}