Vainu MCP Server

A Model Context Protocol (MCP) server for Vainu that enables AI assistants to search companies, retrieve company context, discover relevant fields and event types (via list_organization_fields and get_event_types_reference with skills), and perform document search across Nordic company data.

Getting Started

Via Vainu (Production)

1. Complete the guided OAuth login flow to connect your Vainu account.
2. Confirm with your Vainu contact person that you have the necessary permissions:
   • Vainu country databases you need
   • Vainu MCP permission
   • Vainu Discovery Agent
   • Vainu API (API access - Standard)
3. Enter the MCP server URL into your client: https://mcp.vainu.ai/mcp

Claude

Go to Settings → Connectors → Add MCP Server, and enter the server URL https://mcp.vainu.ai/mcp.

Gemini CLI

Add the following to ~/.gemini/settings.json:

{
  "mcpServers": {
    "vainu": {
      "url": "https://mcp.vainu.ai/mcp"
    }
  }
}

Microsoft Palantir Foundry (and similar OAuth-based platforms)

For platforms like Palantir Foundry that require explicit OAuth credentials instead of an interactive login flow, use the client credentials method. This is confirmed to work with Foundry's MCP connector.

Step 1: Create an OAuth Application in Vainu

1. Go to vainu.app/settings/api-access/ and click Create Application.
2. Copy the Client Secret immediately after creation — it will not be shown again.
3. Detailed instructions with screenshots: developers.vainu.com/v3/docs/client-credentials-authentication

Step 2: Configure the MCP Connection in Foundry

In Foundry's Edit Connection dialog (Tools section), enter the following:

After saving the connection, attach it to your Foundry agent.

Other MCP-compatible clients

Any client that supports HTTP/SSE transport and OAuth 2.0 can connect. The server uses OAuth 2.0 with PKCE for secure authentication. Clients discover OAuth endpoints at:

• /.well-known/oauth-authorization-server (OAuth discovery)
• /authorize (authorization)
• /token (token exchange, including refresh)
• /auth/callback (OAuth callback handler)

Features

AI-Powered Suggestions

• Get Event Types Reference: Return the canonical event types list for the event-type-selection skill. Use with the skill to pick event type IDs that match the user's intent. Pass those IDs to get_signals_news (tags) or get_company_context (leads).

Company Data

• Search Companies: Simple search by business ID, domain, or company name. Supports databases: FI, SE, NO, DK.
• Advanced Company Search (VQL): Build and execute complex queries using Vainu Query Language (VQL).
  • get_query_reference: Learn VQL syntax.
  • search_filter_values: Find valid industry codes, technologies, and other filter values.
  • search_address_filter_values: Find valid city, municipality, and region names.
  • validate_query: Validate your VQL query before execution.
  • query_organizations: Execute the query to find companies.
• Get Company Context: Retrieve comprehensive company context including:
  • Database fields (configurable via list_organization_fields; see organization-field-selection skill)
  • Website content
  • Financial statements
  • Leads (event type IDs from get_event_types_reference and the event-type-selection skill)
  • Documents: budget, job_postings, meetings, financial_statement (with vector search)

Metadata Discovery

• List Organization Fields: Discover available company fields, their metadata (type, description), and filter capabilities.

Document Search

• Document Search: Vector search across document types with filters for:
  • Content classes: announcements, blog, budget, cases, decision_maker_profile, esg_report, events, financial_statement, job_posting, meetings, news, other, post, publications, regulatory, remiss
  • Date range (since)
  • Countries
  • Business IDs (optional)
  • Multiple search prompts (optional)

Examples

• Company search and context:
  • "Search for companies named Nokia in Finland"
  • "Find companies with domain nokia.com"
  • "Get context for business ID FI1234567-8 including their website content and financials"
  • "What fields should I look at when researching companies for a sales campaign?"
• Advanced Search (VQL):
  • "Find all SaaS companies in Helsinki with turnover > 1M" (Agent would: search industry/tech codes → build query → validate → execute)
  • "How do I query for companies using 'React' technology?" (Agent uses get_query_reference and search_filter_values)
• Event and lead discovery:
  • "What event types are relevant for companies doing layoffs in Norway?"
  • "Suggest event types for a prompt about new product launches in Sweden"
• Document search:
  • "Find budget documents and meeting minutes for companies in Denmark"
  • "What ESG reports or regulatory documents mention sustainability in Norway?"

API Reference

Endpoints

Tools

get_event_types_reference

Return the canonical event types reference for the event-type-selection skill. Use with the skill to pick event type IDs that match the user's intent. Pass those IDs to get_signals_news (tags) or get_company_context (leads).

Parameters:

Returns: list[object] – Each object has id, label, category, databases. Empty databases = available in all countries. If include_descriptions is true, each object also has what_it_means and use_cases.

list_organization_fields

Discover which company (organization) fields exist and their metadata. Call this before building a query or requesting company context to choose valid field names.

Parameters:

Returns: list[dict] – List of field metadata objects (path, type, description, etc.)

search_companies

Search the Vainu database for companies by business ID, domain, or company name.

Parameters:

Returns: list[object] – List of companies

get_company_context

Retrieve comprehensive company context including database fields, website content, financial statements, leads, and documents. Uses vector search for document types.

Parameters:

Document Types (for documents parameter):

Returns: string – Company context information

document_search

Vector search across document types with filters for content classes, date range, countries, and business IDs.

Parameters:

Content Classes (for content_classes parameter):

Returns: object – Search results

get_query_reference

Get VQL (Vainu Query Language) reference documentation. Call this before constructing a company query to learn the syntax, operators, and see examples.

Parameters: None

Returns: string – VQL reference documentation

search_filter_values

Search for allowed VQL filter values by keyword (industry codes, custom industries, legal entities, technologies).

Parameters:

Returns: list[dict] – List of matching entries with codes/values/IDs and labels

search_address_filter_values

Get address filter value options for VQL (cities, municipalities, postal_codes, regions).

Parameters:

Returns: dict – Dict with lists of address options

validate_query

Validate a company query before using it with query_organizations.

Parameters:

Returns: dict – Validation result (valid: boolean, error: string, etc.)

query_organizations

Query organizations from the Vainu API using a VQL query object.

Parameters:

Returns: list[dict] – List of companies with requested fields

More Information

• Vainu Platform
• Model Context Protocol
• MCP Inspector