Surname MCP integration

Availability

The public read-only MCP service is available at https://nameideahub.com/mcp. Add this URL as a remote MCP server in a compatible client. No account or API key is required.

The transport is Streamable HTTP with JSON responses and no persistent sessions. The current SDK supports initialization-based MCP versions through 2025-11-25; support for newer protocol revisions is not claimed.

Search surnames

search_surnames filters recorded names by substring, prefix, initial, spelling length and Census rank. Results are ordered by ascending Census rank. Each response includes the total match count, an offset and a next offset when more results are available.

{
  "name": "search_surnames",
  "arguments": {
    "scope": "source",
    "initial": "S",
    "minLength": 5,
    "maxLength": 7,
    "limit": 5
  }
}

Optional inputs are scope, query, prefix, initial, minLength, maxLength, minRank, maxRank, limit and offset. The default scope is source; the default limit is 20 and the maximum is 50. Length bounds are 1–64, rank bounds are 1–3,000 and offsets are 0–3,000. Text filters are surname fragments of up to 64 characters, not prompts for generating new names. Invalid bounds and unknown inputs are rejected.

Look up a record

get_surname_record accepts a stable surname id returned by search, such as smith. It returns the recorded spelling, rank, count, official source and any existing Nameidea collection pages that include the name.

{ "name": "get_surname_record", "arguments": { "id": "smith" } }

Each successful tool result is available as both structured content and a JSON text representation. An absent record returns status: not_found and record: null. This only means the name is absent from the imported subset.

Data coverage

The source scope contains 3,000 imported records from the 2010 U.S. Census surname dataset. This is a subset of that dataset. Census ranks and counts describe recorded use in the United States in 2010, not current worldwide popularity.

• source: 3,000 imported records.
• last-name-ideas: the 500-name spelling-length collection.
• family-name-ideas: the 400-name initial collection.
• website: 512 distinct surnames across the two overlapping collections.

Responses include a content-based dataVersion, source details, dataset counts and limitations. Names outside the website collections link to the official data source; they do not have individual Nameidea pages. These tools do not provide meanings, ancestry, nationality, legal eligibility, trademark checks or domain availability. Browser favorites and first-name drafts are not accessible.

Request limits and privacy

The service accepts one JSON-RPC message per POST request, with a maximum body size of 16 KiB and a 10-second request deadline. GET and DELETE return 405. Disallowed browser origins return 403; configured browser access is limited to the Nameidea origin. Clients without an Origin header can connect.

Anonymous traffic has approximate limits of 120 requests per minute per egress IP and 600 requests per minute for the service, independently at each Cloudflare location. Shared networks may share a limit. A 429 response includes Retry-After; request timeouts return 504. Limits are not an exact global quota.

Application logs contain request identifiers, status codes and elapsed time. They do not include query arguments or IP addresses. MCP calls do not send Google Analytics page views. See the Privacy notice and contact hello@nameideahub.com for questions or availability updates.