MCP documentation

MCP Server Tool Reference

Complete reference for all tools exposed by the NordicContacts MCP server. Use these tools from any MCP-compatible AI agent to look up companies, contacts and build filtered target groups.

Quick start

Create an account. Register here
Eligible new accounts get the free trial during registration. Manage your subscription from the account page; no manual token is needed for OAuth-compatible clients. Go to account
Add the MCP URL below to an MCP client such as Claude, sign in with your NordicContacts account in the browser window that opens, approve access, and enable the connector to start calling tools.

Configuration

Add the MCP URL below to any client that supports MCP OAuth, including Claude, VS Code and ChatGPT. Sign in through the browser; the client handles the token automatically.

OAuth-compatible MCP clients

Use the hosted MCP URL directly. No manual JSON or token setup is needed when your client supports OAuth.

MCP endpoint

https://nordiccontacts.eu/mcp

Add a new MCP server or connector in your client.
Paste the NordicContacts MCP URL.
Sign in with your NordicContacts account in the browser window and approve access.
Enable the connector and start calling tools.

Clients without OAuth support

If your MCP client does not support MCP OAuth yet, open token management to create a token and copy the ready-made JSON configuration with the actual token value.

Open token management

The server uses HTTP Streamable transport. OAuth is preferred when the client supports it; otherwise authenticate with a Bearer token in the Authorization header.

Authentication

Claude, VS Code, ChatGPT and other MCP OAuth-compatible clients prompt you to sign in and approve access when you add the MCP URL; you do not need to create a token manually. Clients without OAuth support must send an Authorization: Bearer header with a valid manual MCP access token. Tokens require an active subscription or free trial, can be revoked from your account page, and manual token values are shown only once at creation time. Access tokens have no scheduled expiry; revoking a token disconnects that client, and reconnecting requires completing the sign-in flow again.

Tools

The server exposes the following tools. All tools require authentication. Discovery, taxonomy and count tools are free; retrieval tools consume your shared subscription balance with a minimum of 1 unit per call.

describe_tools

Lists the available MCP tools grouped by purpose, with usage hints and guidance for keyword taxonomy and company list filters. Useful for self-discovery before calling other tools.

Parameters

Name	Type	Required
includeExamples	boolean	No

Returns: { server, tools[], guidance }Billing unit: Free

service_info

Returns service details, pricing, setup steps, and the authenticated account's subscription and remaining quota.

Parameters

Name	Type	Required

Returns: { service, pricing, setup, multiUser, account }Billing unit: Free

find_contact_by_email

Resolves one individual contact from a known email address. Returns at most one contact with name, title, responsibility area, employer and market context. Costs 1 contact unit per call.

Parameters

Name	Type	Required
email	string	Yes

Returns: { contact }Billing unit: CONTACT

find_companies

Finds companies by internal companyId, businessId, website domain or company name for identity resolution (typically 1–3 best matches). companyId is the internal database ID returned as id in company records or companyId in contact rows, not the business registration ID. Use companyId to retrieve full company details; it takes precedence over other identifiers, while countryId still restricts the lookup. Returns an unambiguous match in resolvedCompany without candidates; otherwise returns ranked candidates with match scores and ambiguity metadata. The candidate limit defaults to 10 and is capped at 20. Costs 1 company unit for a resolved match, or 1 unit per returned candidate when the result is ambiguous (minimum 1 unit per call).

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
domain	string	No
companyName	string	No
countryId	number	No
limit	number	No

Returns: { resolvedCompany, candidates?: Company[], isAmbiguous }Billing unit: COMPANY

resolve_company_by_domain

Resolves companies by exact website domain — the fastest direct lookup. Returns a single match in resolvedCompany without candidates; multiple matches return isAmbiguous=true and candidates, and no matches return an empty candidates array. The limit defaults to 20 and is capped at 20. Costs 1 company unit per returned company, minimum 1 unit per call.

Parameters

Name	Type	Required
domain	string	Yes
countryId	number	No
limit	number	No

Returns: { resolvedCompany, candidates?: Company[], isAmbiguous }Billing unit: COMPANY

list_company_contacts

Retrieves contacts that belong to one company with deterministic limit/offset pagination. Returns full company details once in resolvedCompany without candidates, and compact contact rows with person fields and companyId rather than repeated company details. Ambiguous company names return candidates for re-resolution. Costs 1 contact unit per returned contact, minimum 1 unit per call.

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
companyName	string	No
countryId	number	No
contactInfoFilter	'email' \| 'phone' \| 'both'	No
limit	number	No
offset	number	No

Returns: { resolvedCompany, candidates?: Company[], isAmbiguous, contacts[] }Billing unit: CONTACT

list_countries

Lists available supported countries — Finland, Sweden and Estonia — with the IDs used in countryId filters. Free to call.

Parameters

Name	Type	Required
search	string	No
limit	number	No

Returns: { countries[] }Billing unit: Free

list_industry_groups

Lists high-level industry groups with IDs for industryGroupIds filters. Free to call.

Parameters

Name	Type	Required
search	string	No
limit	number	No

Returns: { industryGroups[] }Billing unit: Free

list_industries

Lists detailed industry codes for a country (Finland: TOL 2025, Sweden: SNI 2025, Estonia: EMTAK 2025) for industryCodes filters. Search matches English names, industry codes, and localized names where available (Finnish for Finland and Swedish for Sweden; e.g. programming, ohjelmisto, datakonsult). Defaults to 200 results, with a maximum of 500; use offset to paginate. Free to call.

Parameters

Name	Type	Required
search	string	No
limit	number	No
offset	number	No
countryId	number	Yes

Returns: { industries[] }Billing unit: Free

list_main_responsibility_areas

Lists broad responsibility areas (e.g. Sales, IT, Marketing) with IDs for mainResponsibilityAreaIds filters. Free to call.

Parameters

Name	Type	Required
search	string	No
limit	number	No

Returns: { mainRespTypes[] }Billing unit: Free

list_job_functions

Lists job function categories with IDs for jobFunctionIds filters; finer-grained than main responsibility areas. Free to call.

Parameters

Name	Type	Required
search	string	No
limit	number	No

Returns: { jobFunctions[] }Billing unit: Free

list_keyword_categories

Lists all main-level company keyword categories with canonical names and Finnish, Swedish and English labels for keywordCategoryFilter. Free to call.

Parameters

Name	Type	Required

Returns: { categories[] }Billing unit: Free

search_keyword_subcategories

Searches company keyword subcategories by canonical or localized wording, optionally narrowed by main categories, for keywordCategoryFilter. Free to call.

Parameters

Name	Type	Required
search	string	No
mainCategories	string[]	No
limit	number	No
offset	number	No

Returns: { subcategories[] }Billing unit: Free

count_contact_segment

Counts contacts matching the segment filters without loading contact rows — use for "how many contacts" questions. Free to call.

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
countryId	number	Yes
regionName	string	No
industryGroupIds	number[]	No
industryCodes	string[]	No
mainResponsibilityAreaIds	number[]	No
jobFunctionIds	number[]	No
turnoverMin	number	No
turnoverMax	number	No
profitMin	number	No
profitMax	number	No
personnelMin	number	No
personnelMax	number	No
foundedYearMin	number	No
foundedYearMax	number	No
newContactsWithinDays	number	No
newResponsibilityAssignmentsWithinDays	number	No
contactInfoFilter	'email' \| 'phone' \| 'both'	No
organizationLevels	string[]	No
webshopStatus	'identified' \| 'not_identified' \| 'not_crawled'	No
webshopPlatforms	string[]	No
targetMarket	'b2b' \| 'b2c' \| 'both' \| 'unknown' \| 'not_crawled'	No
keywordCategoryFilter	object	No
customerListMode	'ignore' \| 'exclude' \| 'limit'	No

Returns: { totalCount }Billing unit: Free

count_company_segment

Counts companies matching the segment filters without loading rows — use for "how many companies" questions. Free to call.

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
countryId	number	Yes
regionName	string	No
industryGroupIds	number[]	No
industryCodes	string[]	No
mainResponsibilityAreaIds	number[]	No
jobFunctionIds	number[]	No
turnoverMin	number	No
turnoverMax	number	No
profitMin	number	No
profitMax	number	No
personnelMin	number	No
personnelMax	number	No
foundedYearMin	number	No
foundedYearMax	number	No
newContactsWithinDays	number	No
newResponsibilityAssignmentsWithinDays	number	No
companyContactFilter	'all' \| 'email' \| 'phone' \| 'both'	No
organizationLevels	string[]	No
webshopStatus	'identified' \| 'not_identified' \| 'not_crawled'	No
webshopPlatforms	string[]	No
targetMarket	'b2b' \| 'b2c' \| 'both' \| 'unknown' \| 'not_crawled'	No
keywordCategoryFilter	object	No
customerListMode	'ignore' \| 'exclude' \| 'limit'	No

Returns: { totalCount }Billing unit: Free

list_contact_segment

Returns a filtered contact segment using the same criteria as the web search page, with deterministic limit/offset pagination. Compact rows contain person fields, companyId and basic employer context, without full company descriptions or financial details. Defaults to 100 contacts and returns at most 100 per page; use offset for subsequent pages. Costs 1 contact unit per returned contact, minimum 1 unit per call.

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
countryId	number	Yes
regionName	string	No
industryGroupIds	number[]	No
industryCodes	string[]	No
mainResponsibilityAreaIds	number[]	No
jobFunctionIds	number[]	No
turnoverMin	number	No
turnoverMax	number	No
profitMin	number	No
profitMax	number	No
personnelMin	number	No
personnelMax	number	No
foundedYearMin	number	No
foundedYearMax	number	No
newContactsWithinDays	number	No
newResponsibilityAssignmentsWithinDays	number	No
contactInfoFilter	'email' \| 'phone' \| 'both'	No
organizationLevels	string[]	No
webshopStatus	'identified' \| 'not_identified' \| 'not_crawled'	No
webshopPlatforms	string[]	No
targetMarket	'b2b' \| 'b2c' \| 'both' \| 'unknown' \| 'not_crawled'	No
keywordCategoryFilter	object	No
customerListMode	'ignore' \| 'exclude' \| 'limit'	No
limit	number	No
offset	number	No

Returns: { contacts[] }Billing unit: CONTACT

list_company_segment

Lists companies matching the segment criteria (country, industry, size, webshop, target market, keywords) with deterministic pagination. Defaults to 100 companies and returns at most 100 per page; use offset for subsequent pages. Costs 1 company unit per returned company, minimum 1 unit per call.

Parameters

Name	Type	Required
companyId	number	No
businessId	string	No
countryId	number	Yes
regionName	string	No
industryGroupIds	number[]	No
industryCodes	string[]	No
mainResponsibilityAreaIds	number[]	No
jobFunctionIds	number[]	No
turnoverMin	number	No
turnoverMax	number	No
profitMin	number	No
profitMax	number	No
personnelMin	number	No
personnelMax	number	No
foundedYearMin	number	No
foundedYearMax	number	No
newContactsWithinDays	number	No
newResponsibilityAssignmentsWithinDays	number	No
companyContactFilter	'all' \| 'email' \| 'phone' \| 'both'	No
organizationLevels	string[]	No
webshopStatus	'identified' \| 'not_identified' \| 'not_crawled'	No
webshopPlatforms	string[]	No
targetMarket	'b2b' \| 'b2c' \| 'both' \| 'unknown' \| 'not_crawled'	No
keywordCategoryFilter	object	No
customerListMode	'ignore' \| 'exclude' \| 'limit'	No
limit	number	No
offset	number	No

Returns: { companies[] }Billing unit: COMPANY

Billing

Starter and Pro use a shared balance across MCP, REST API, and subscribed Excel exports. Included contacts are consumed first, then prepaid top-up contacts. One-time Excel purchases are separate and use a dedicated one-time order flow. Each metered tool call costs at least 1 unit; most retrieval tools also charge 1 unit per returned row. The billing unit for each tool is listed below.

MCP Playground (coming next)

An interactive testing area is planned for advanced configuration. Until then, explore MCP use cases and manage access tokens from account settings.

Explore MCP use cases View REST API page Manage MCP account

View plans Go to account