# Register your MCP server How a vendor or its AI agent lists an official remote MCP server in the Koskamo directory: two API calls and a DNS or well-known-file proof of domain control, published at once with no review. Web version: https://koskamo.com/explore/register ## Who qualifies List a server only if you operate it. The directory accepts official remote MCP servers run by the company behind the product, reachable as one streamable-HTTP endpoint over https. Community-hosted wrappers and local stdio servers do not qualify. There is no editorial review: a server is published as soon as you prove control of the endpoint's domain and it passes the live check. Admins can still hide or remove any listing. ## Fields Send these as one JSON object in step 1. Unknown fields are ignored. - `id`: Required. Lowercase kebab-case, at most 64 characters. Permanent page slug: the listing lives at https://koskamo.com/explore/. - `name`: Required. Product name, at most 80 characters. - `operator`: Required. Company that runs the server, at most 80 characters. - `endpoint`: Required. The streamable-HTTP endpoint, an https URL without credentials, at most 500 characters. Its host is the one you prove. - `category`: Required. One of: docs-reference, developer-tools, cloud-infrastructure, data-analytics, ai-ml, commerce, payments, productivity, project-management, crm-marketing, design. - `auth`: Required. One of: none (No sign-in), oauth-optional (Optional OAuth sign-in), oauth (OAuth sign-in), api-key (API key). The live check verifies it: none and oauth-optional must answer initialize and tools/list anonymously; oauth and api-key must refuse an anonymous initialize with 401 or 403. - `description`: Required. 20 to 600 characters, factual. - `useCases`: Required. 1 to 6 tasks from your own documentation, each at most 200 characters. - `requirements`: Optional. Up to 4 prerequisites a user must already have — a vendor account, paid subscription, or API key issued by you — each at most 200 characters. Endpoint sign-in itself is covered by auth. - `companyUrl`: Optional. Your company’s https website, without credentials, at most 500 characters. Displayed separately from MCP documentation. Send an empty string to clear it. - `docsUrl`: Required. Your https documentation page for this MCP server, at most 500 characters. - `tools`: Optional. At most 100 names; replaced by the live tools/list on every passing check, and only allowed when tools/list works without sign-in. - `email`: Optional, recommended. A contact address for notices about this listing (see below). ## Step 1: request a claim token POST the fields. Nothing is created yet. The 201 response holds the token, the exact TXT names and well-known URL to publish it at, the verify request to send next, and a nextSteps list. Step 1 request: ``` curl -sS -X POST 'https://koskamo.com/api/v1/mcp-directory/servers' \ -H 'Content-Type: application/json' \ --data-raw '{ "id": "example-docs", "name": "Example Docs", "operator": "Example Inc.", "endpoint": "https://mcp.example.com/mcp", "category": "docs-reference", "auth": "none", "description": "Search and read the public Example product documentation from any MCP client.", "useCases": [ "Look up an Example API parameter while writing code" ], "docsUrl": "https://example.com/docs/mcp", "email": "mcp-team@example.com" }' ``` The token stays valid for 7 days (expiresAt in the response). A 409 means the id is taken or another listing already uses the endpoint host; the response links the key-recovery flow for that listing. ## Publish the proof (one option) Option A, DNS TXT record: name _koskamo-claim., value exactly the token. The domain may be the endpoint host or any parent with at least two labels. For https://mcp.example.com/mcp that is _koskamo-claim.mcp.example.com or _koskamo-claim.example.com. TXT record: ``` _koskamo-claim.mcp.example.com. TXT "koskamo-claim=" ``` DNS proofs are looked up through public resolvers (1.1.1.1 and 8.8.8.8), not a cached ISP resolver, so a new TXT record is usually visible within seconds to a minute. Option B, well-known file: serve https:///.well-known/koskamo-claim on the endpoint's exact host (a parent such as example.com does not count), over https, with no redirect to another host. The body must contain the token on a line of its own; plain text is simplest. Contents of https://mcp.example.com/.well-known/koskamo-claim: ``` koskamo-claim= ``` Option C, Email proof: send "method": "email" and "proofEmail": "@" in step 1, where the mailbox is one of admin, administrator, webmaster, hostmaster, postmaster (no plus-tags) and the domain is the endpoint host or one of its parents. A single-use link that expires in 48 hours is mailed there; a person must open it and press Confirm before verify succeeds. A confirmed email proof stands for 365 days. Use this when you cannot change DNS or the web server. The response to step 1 says where the link went and never contains the link's token. Limits: 3 per address per day and 5 per IP per hour; starting again sends a new link and the old one stops working. Step 1 request with an email proof: ``` curl -sS -X POST 'https://koskamo.com/api/v1/mcp-directory/servers' \ -H 'Content-Type: application/json' \ --data-raw '{ "id": "example-docs", "name": "Example Docs", "operator": "Example Inc.", "endpoint": "https://mcp.example.com/mcp", "category": "docs-reference", "auth": "none", "description": "Search and read the public Example product documentation from any MCP client.", "useCases": [ "Look up an Example API parameter while writing code" ], "docsUrl": "https://example.com/docs/mcp", "email": "mcp-team@example.com", "method": "email", "proofEmail": "admin@example.com" }' ``` ## Step 2: verify and publish POST the token to the verify URL from step 1. It tries the well-known file, then TXT records from the endpoint host up through its parents; send "method": "http" or "dns" or "email" to check only one (an email proof started in step 1 needs "method": "email"). Only when a proof is found and the live check passes is the listing created. Step 2 request: ``` curl -sS -X POST 'https://koskamo.com/api/v1/mcp-directory/servers/example-docs/verify' \ -H 'Content-Type: application/json' \ --data-raw '{ "token": "koskamo-claim=" }' ``` The 201 response contains status "published", the listing URL, the owner key (shown once), and how to edit. ## When verify answers 422 422 means nothing was published and the token is still valid. The response says which check failed: - proofs lists each place that was checked and why it did not match. Publish the TXT record or well-known file shown in step 1 (or confirm the emailed link for an email proof), wait a minute, then call verify again with the same token. - For an email proof, the proof detail says the link is not confirmed yet or has expired. Ask whoever reads the proof mailbox to open the link, press Confirm, then call verify again with the same token. If the link expired, send step 1 again with method email. - liveCheck states the live-check failure. Make the endpoint answer as its declared auth class (see liveCheck), then call verify again with the same token. - 410 means the token expired. Send step 1 again for a new token (tokens last 7 days) and publish the new one. - 429 means the rate limit was hit. Wait retryAfter seconds, then retry the same request. Every refusal carries a guide link and, where the remedy is known, a one-line fix. ## Store the owner key safely The owner key starts with kmo_owner_, is scoped to this one listing, and is shown once. Store the owner key in a secret manager or an untracked environment variable at once. Never print it to logs or chat transcripts and never commit it; it is shown exactly once. Koskamo stores only a hash, so it cannot show the key again. ## Update the listing PATCH the listing with the owner key as a Bearer token and only the fields to change. With a verified proof the edit publishes at once; changing endpoint, auth, or docsUrl re-runs the live check first. An endpoint moved to a host your proof does not cover, or an edit to a hidden listing, goes to review (202). The id never changes, and owners cannot hide or delete a listing. Owner edit: ``` curl -sS -X PATCH 'https://koskamo.com/api/v1/mcp-directory/servers/example-docs' \ -H "Authorization: Bearer $KOSKAMO_OWNER_KEY" \ -H 'Content-Type: application/json' \ --data-raw '{"description":"Search and read the public Example product documentation from any MCP client."}' ``` Keep the TXT record or well-known file in place. Proofs are re-checked weekly; a failed re-check stops the owner key until the proof is restored. An email proof lapses 365 days after it was confirmed. ## Recover a lost key POST to the listing's recover URL for a fresh token, publish it the same way (or send {"method": "email", "proofEmail": "@"} to have a confirm link mailed), and call verify. You get a new owner key and every earlier self-registration key stops working. A contact email cannot recover a key; only a domain proof can. Start recovery: ``` curl -sS -X POST 'https://koskamo.com/api/v1/mcp-directory/servers/example-docs/recover' ``` ## Optional contact email Include email in step 1 so Koskamo can reach you if the listing is hidden after failed live checks, your proof lapses, or the owner key is rotated or revoked. After publish it receives one confirmation message and nothing else until confirmed. It is never shown publicly and never grants ownership. ## Using the MCP tool instead Connected to the Koskamo MCP server (https://koskamo.com/api/mcp)? The koskamo_register_mcp_server tool runs the same two steps: call it with the fields and no token for step 1, publish the proof, then call it again with id and token for step 2. ## Rate limits - Step 1 and key recovery: 5 requests per hour per IP. - Ownership emails: 3 per address per day and 5 per IP per hour. - Verify: 30 requests per hour per IP, so retry after fixing a proof rather than polling. - Pending registrations expire after 7 days. Machine-readable spec: https://koskamo.com/api/v1/openapi.json (tag mcp-directory). This guide as Markdown: https://koskamo.com/explore/register.md.