names.dev / integration reference
One service. Your assistant.
Use public MCP tools or a REST JSON request to find, check, refine and compare names with the same domain evidence as the website.
Open the connection setupConnection
The primary direct endpoint is https://api.names.dev/mcp. The setup page provides copyable configuration. The alias https://names.dev/api/mcp proxies to that service and shares the proxy's public request allowance, so prefer the direct endpoint for regular use.
If the primary custom domain is temporarily unavailable, the fallback is https://names-api-v2.nima-672.workers.dev/mcp.
The transport is stateless Streamable HTTP with JSON responses and protocol negotiation through 2025-11-25. Public tools do not require an API key or Rufio account. MCP clients initialize over POST; GET returns 405 and no session is fabricated.
| Tool | Use it for |
|---|---|
| names_search | An exact domain, a bare label or a product brief. Carry preferred endings, budget in USD cents, result limit and explicitly rejected labels (up to 48). |
| names_check | One full domain, with exact-domain intent preserved before alternatives. |
| names_refine | Original brief plus feedback. Keep endings, budget and limit; previousNames contains up to 48 explicitly rejected labels, without domain endings. |
| names_compare | Two or three distinct full domains, verified side by side. One search allowance per domain. |
| names_portfolio_search | Published, control-checked portfolios. The acquisition budget and returned asking price cover the whole lot, never each domain. |
| names_shortlist_create | Explicitly create a 30-day unlisted link for up to eight selected domains and a reviewed brief. Keep the separate owner revocation key private. |
| names_shortlist_read | Read shared names and preferences using a reader capability. Saved selections are not live availability evidence; recheck the domains. |
| names_shortlist_revoke | Revoke a shared link using its private owner capability. Revocation does not delete local browser selections. |
Run the first useful request
On the connection setup page, choose MCP requests for a prompt to paste into your connected assistant, or REST examples for executable curl requests. Both include search, exact-domain checks, refinement and whole-portfolio discovery. Test connection sends an MCP initialize request without running a search; it is the appropriate check when opening the server URL in a browser returns 405.
When refining, retain the original brief, preferred endings, budget and result limit. MCP uses brief, feedback and previousNames; REST sends the original brief plus naming feedback in query and the rejected labels in excludeLabels. Exclusions contain labels without endings and apply to alternatives; explicitly requested names remain checked. Do not silently turn every previously seen name into a rejection.
Search and MCP portfolio budgets use USD cents: $500 is 50000. The REST portfolio catalog uses dollars in max_price_usd: $2,500 is 2500.00. Its asking-price ceiling covers the complete lot, and budget-filtered results require a known asking price within that ceiling.
Read the response
Tool results include JSON in structuredContent and text for clients that use content blocks. Each tool publishes its input and output JSON schemas. Inspect isError before using a tool result.
resultscontains name labels, meaning and fit explanations when supplied, plus domain paths.registrationandoffersare distinct. Read provider, source trust, checked timestamp, expiry, listing type, currency, price and returned URL.checkout_required, RDAP/DNS hints and search hints require verification at the provider. Unknown evidence is never an availability guarantee.diagnostics.issuesidentifies provider limitations; empty results may be appropriate. A cache hit preserves original evidence timestamps.
Guidance and discovery
MCP resources names://guide and names://capabilities contain public operating guidance. Prompts name_a_project and refine_a_shortlist provide starting workflows. There are no private user resources.
Import OpenAPI for the supported HTTP operations. All four search modes use POST /api/v2/search through the canonical website API; the direct runtime uses /v2/search. Public portfolio discovery uses GET https://names.dev/api/v1/marketplace/lots. The examples use these distinct endpoints. Native side-by-side comparison is an MCP tool; an HTTP client can check each exact domain separately before comparing the evidence.
Limits and acquisition
Public clients have six search allowances and thirty requests per minute. Aggregate limits also apply. Follow Retry-After for HTTP rate-limit responses and avoid retry loops. Comparisons consume one search allowance for each domain.
This integration does not purchase, register, transfer, send offers, edit DNS or access private accounts. Complete acquisition using the returned registrar or marketplace URL. Trademark screening and legal clearance are separate jobs.
Configuration syntax references: official OpenAI documentation and Claude Code documentation. The HTTP transport is tested with the official MCP SDK; support in other named assistant apps is not independently verified.