Skip to main content
Glama
@kooperativa_team/mcp-server

@kooperativa_team/mcp-server

Official

@kooperativa_team/mcp-server

MCP (Model Context Protocol) server for the Kooperativa API.

Gives any MCP-compatible AI assistant (Claude Desktop, Kiro, Cursor, Windsurf, Kilo, etc.) direct access to Kooperativa's B2B data lake: enrich and search professional profiles and companies, surface hiring signals and recent job changes, resolve an email address to a profile, and manage webhook monitors, all from a conversation.

Kooperativa holds structured people and company records. It deliberately has no contact data: no email addresses and no phone numbers.

Installation

Requires Node.js 18+ and a Kooperativa API key. Get one from your account dashboard.

Add the server to your MCP client's configuration:

{
  "mcpServers": {
    "kooperativa": {
      "command": "npx",
      "args": ["-y", "@kooperativa_team/mcp-server"],
      "env": {
        "KOOPERATIVA_API_KEY": "ik_live_..."
      }
    }
  }
}

No local installation step is required, npx resolves and runs the package on demand. Restart your MCP client after adding the config.

Related MCP server: JobDataLake MCP Server

Available tools

Tool

Endpoint

Description

kooperativa_account_info

GET /me

License status and usage breakdown

kooperativa_health_check

GET /health

API liveness probe

kooperativa_enrich_person

GET /person

Full profile lookup by URL, username, or ID

kooperativa_enrich_person_realtime

GET /person/realtime

Same, but from the live source. $0.001 per call, see Billing

kooperativa_check_person

GET /person/check

Cheap existence check before a full lookup

kooperativa_search_people

POST /people/search

Filtered search across the people data lake

kooperativa_bulk_enrich_people

POST /people/bulk-enrich

Enrich up to 100 profiles in one call

kooperativa_person_colleagues

GET /person/colleagues

Current coworkers of a person

kooperativa_person_similar

GET /person/similar

Lookalike profiles by seniority/industry/country

kooperativa_person_job_changes

GET /person/job-changes

Recently started new roles

kooperativa_resolve_email

POST /resolve-email

Resolve an email address you already have to a profile

kooperativa_institution_alumni

GET /institution/alumni

People whose education includes a given school

kooperativa_enrich_company

GET /company

Full company profile lookup

kooperativa_enrich_company_realtime

GET /company/realtime

Same, but from the live source. $0.001 per call, see Billing

kooperativa_check_company

GET /company/check

Cheap existence check before a full lookup

kooperativa_search_companies

POST /companies/search

Filtered search across the company data lake

kooperativa_company_current_employees

GET /company/current-employees

People currently at a company

kooperativa_company_past_employees

GET /company/past-employees

People who used to work at a company

kooperativa_company_headcount_by_seniority

GET /company/headcount-by-seniority

Indexed headcount breakdown

kooperativa_company_hiring_signals

GET /company/hiring-signals

Recently joined employees

kooperativa_company_decision_makers

GET /company/decision-makers

C-level, VP and director profiles at a company

kooperativa_list_monitors

GET /monitors

List active webhook monitors

kooperativa_create_monitor

POST /monitors

Subscribe to change events on a profile/company

kooperativa_delete_monitor

DELETE /monitors

Remove a webhook monitor

Full parameter reference: docs.kooperativa.io.

Server instructions

On connect the server sends the client a short brief (the MCP instructions field) covering the things that are easy to get wrong: the people and company industry taxonomies differ, countries are ISO 2-letter codes, a 404 means "not indexed yet", headcount figures can be unreliable, company-name search is fuzzy, and the realtime tools cost money. It also tells the model to treat profile text as untrusted data.

Billing

Every tool above is included in the workspace license, with no per-call charge, except the two realtime ones. Those read from the live source rather than from the Kooperativa data lake, and are metered at $0.001 per call on top of the license, which is still required.

This matters more here than in a hand-written integration, because the model decides when to call a tool. Three things follow from that:

  • A miss still costs. A call is billed whenever the live source actually answered, so a not-found result costs the same as a hit, because the lookup happened either way. Only a 503, meaning the source could not be reached at all, is not billed.

  • There is no cache. Two realtime calls for the same person bill twice. The result is written back to the data lake, so the free kooperativa_enrich_person returns it afterwards at no cost.

  • The tool descriptions carry the price, so an agent choosing between the free and metered variant has the cost in front of it. If you wrap this server in your own agent, keep that wording rather than trimming the descriptions for brevity.

If you want to rule out metered spend entirely, do not expose the two *_realtime tools to the model.

Authentication

The server looks for the key in this order:

  1. KOOPERATIVA_API_KEY in the environment, when it has the shape of a real key (ik_live_...).

  2. The key stored in ~/.kooperativa/config.json by the login command (same file the Kooperativa CLI uses).

The key is never logged, hardcoded, or transmitted anywhere other than as the Authorization: Bearer header on requests to https://kooperativa.io/api/v1.

Store the key once with login

Some MCP clients cannot pass a secret safely (they pass the text of a placeholder such as ${KOOPERATIVA_API_KEY} instead of expanding it, or do not inherit your shell environment). For those, run this once in a terminal:

npx -y @kooperativa_team/mcp-server login

It asks for the key with input hidden, checks it against the API, and saves it with mode 0600. It prints only your account email and license state, never the key. Restart your MCP client afterwards. The client config then needs no env block at all.

An environment value that does not look like a key is ignored, so an unexpanded placeholder falls back to the stored key instead of causing a 401.

Never paste the key into a chat, a prompt, or a committed config file. Keep it in the login file, your MCP client's env block, or a secrets manager.

Toolsets

By default the server registers all 24 tools. Set KOOPERATIVA_MCP_TOOLSET=read to register only the 18 read-only data tools: no real-time (metered) lookups, no monitors (webhook subscriptions) and no email-to-profile lookup. The plugin and extension listings for Kiro, Cursor and Claude use this set.

{
  "mcpServers": {
    "kooperativa": {
      "command": "npx",
      "args": ["-y", "@kooperativa_team/mcp-server"],
      "env": { "KOOPERATIVA_MCP_TOOLSET": "read" }
    }
  }
}

Every tool carries a title and the MCP annotations readOnlyHint, destructiveHint, idempotentHint and openWorldHint. Responses are compact JSON, to keep token use low.

Self-hosting over Streamable HTTP

The package also ships kooperativa-mcp-http, a stateless Streamable HTTP server for clients that connect to a URL instead of spawning a process.

export KOOPERATIVA_API_KEY="ik_live_..."
export MCP_ACCESS_TOKEN="$(openssl rand -base64 32)"
npx -y -p @kooperativa_team/mcp-server kooperativa-mcp-http

Variable

Required

Default

Meaning

MCP_ACCESS_TOKEN

yes

none

Bearer token every request must send. Without it the server refuses all requests (fail closed).

KOOPERATIVA_API_KEY

yes

none

Your Kooperativa key, used for the upstream calls.

PORT

no

3100

Listen port.

HOST

no

127.0.0.1

Bind address.

Security notes for self-hosting:

  • One server is one account. Every caller that holds MCP_ACCESS_TOKEN spends your license and your realtime credits. Do not share the token or the URL.

  • Terminate TLS in front of it (Caddy, nginx) and keep the default loopback bind. Plain HTTP carries the bearer token in the clear.

  • Requests are capped at 1 MiB, the token is compared in constant time, and request headers and bodies are never logged.

  • Rotate MCP_ACCESS_TOKEN if it is ever exposed.

License

MIT

Support

support@kooperativa.io

Available Tools

19 tools
kooperativa_account_infoKooperativa: account infoA

Get the authenticated Kooperativa account's email, license status (active/plan/expiry), and API usage this month/today, broken down by endpoint. Call this first if you're unsure whether the license is active before running a large batch job.

Inputs: no named parameters.

kooperativa_bulk_enrich_peopleKooperativa: bulk enrich peopleA

Enrich up to 100 profiles in a single call. Pass an array where each item has exactly one of id, username, or linkedin_url. Unmatched identifiers are silently skipped and counted in not_found.

Inputs: profiles (required).

kooperativa_check_companyKooperativa: check company existsA

Cheaply check whether Kooperativa already holds a given company, without fetching the full record. Returns matched id, name, and fetched_at on success, or 404 if not indexed yet.

Inputs: id, username, company_id, linkedin_url.

kooperativa_check_personKooperativa: check person existsA

Cheaply check whether Kooperativa already holds a given profile, without fetching the full record. Returns the matched id, full_name, and fetched_at on success, or 404 if not indexed yet. Use this to filter a list before calling enrich_person on each one.

Inputs: id, username, linkedin_url.

kooperativa_company_current_employeesKooperativa: company current employeesA

List people currently working at a company, by its numeric company_id. Returns lightweight profile previews with offset pagination (total/pages). Pass a result's id to kooperativa_enrich_person for the full record.

Inputs: company_id (required), page, per_page.

kooperativa_company_headcount_by_seniorityKooperativa: company headcount by seniorityA

Breakdown of a company's indexed profiles by seniority level (c-level, vp, director, manager, individual). Useful for org intelligence and account qualification. Counts reflect only Kooperativa's indexed profiles, not the company's real total headcount.

Inputs: company_id (required).

kooperativa_company_hiring_signalsKooperativa: company hiring signalsA

People who recently joined a company — a signal of growth, investment, or expansion. Sorted by join date descending, look-back window configurable in days (default 90, max 365).

Inputs: company_id (required), days, page, per_page.

kooperativa_company_past_employeesKooperativa: company past employeesA

List people who previously worked at a company (held a role there, since moved on), by numeric company_id. Each result includes a past_positions array with the specific role(s) held there. Uses has_more/next_page pagination.

Inputs: company_id (required), page, per_page.

kooperativa_create_monitorKooperativa: create monitorA

Subscribe to change events on a professional profile or company URL. Kooperativa sends a signed POST to webhook_url whenever a change is detected (job change, title change, headline change, location change, skills change for people; staff count or description change for companies). webhook_url must be HTTPS. The returned webhook_secret for signature verification is only shown once, at creation time.

Inputs: type (required), subject_url (required), webhook_url (required), label, +1 more.

kooperativa_delete_monitorKooperativa: delete monitorA

Stop monitoring a profile or company and delete the monitor by its ID.

Inputs: id (required).

kooperativa_enrich_companyKooperativa: enrich companyA

Look up a company's full profile (headcount, follower count, founding year, HQ address, industries, specialities, office locations) from the Kooperativa data lake. Provide exactly one of linkedin_url, username, company_id, or id. Returns 404 if not indexed yet.

Inputs: id, username, company_id, linkedin_url.

kooperativa_enrich_personKooperativa: enrich personA

Look up a person's full professional profile (work history, education, skills, certifications, honors, publications, volunteering) from the Kooperativa data lake. Provide exactly one of linkedin_url, username, or id. Returns 404 if the profile hasn't been indexed yet (no on-demand live scrape).

Inputs: id, username, linkedin_url.

kooperativa_health_checkKooperativa: health checkA

Simple liveness probe for the Kooperativa API. No authentication required. Use to verify connectivity before running a batch job.

Inputs: no named parameters.

kooperativa_list_monitorsKooperativa: list monitorsA

List all active webhook monitors for the authenticated workspace.

Inputs: no named parameters.

kooperativa_person_colleaguesKooperativa: person colleaguesA

List a person's current colleagues (everyone else working at their current company right now). Useful for mapping org structure or finding an alternate contact at a target account. Requires the Kooperativa profile id (from enrich_person or search_people).

Inputs: id (required), page, per_page.

kooperativa_person_job_changesKooperativa: recent job changesA

People who recently started a new job — a strong outreach signal (new role = new budget, new vendor decisions). Optionally filter to people who previously worked at a specific company_id. Sorted most-recent-first.

Inputs: days, page, per_page, company_id.

kooperativa_person_similarKooperativa: similar peopleA

Find people similar to a given person (same seniority, industry, and country), excluding themselves. Useful for lookalike audiences or finding alternative contacts at competing companies. Requires the Kooperativa profile id.

Inputs: id (required), page, per_page.

kooperativa_search_companiesKooperativa: search companiesA

Search the Kooperativa data lake of companies by name, HQ location, industry, and headcount range. All filters are optional and combine with AND logic, but at least one filter is required. min_staff/max_staff are both inclusive and either can be omitted.

Inputs: city, page, query, country, +4 more.

kooperativa_search_peopleKooperativa: search peopleA

Search the Kooperativa data lake of professional profiles using any combination of filters (title, company, location, industry, seniority, headcount, skills, tenure, recent job change, past employer, education). Filters combine with AND logic. Returns lightweight profile previews with pagination; pass a result's id to kooperativa_enrich_person for the full record.

Inputs: city, page, query, title, +18 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 19 tools

    Disambiguation5/5

    Every tool has a clearly distinct role: account/license checks, health probe, person/company lookup/search/check, relationship and signal queries, and monitor lifecycle. Even similar tools like check_person vs enrich_person are explicitly differentiated as cheap existence check vs full profile fetch.

    Naming Consistency4/5

    The shared kooperativa_ prefix and snake_case make the set easy to navigate, and action verbs like search, check, enrich, create, and delete are used consistently. Minor deviations exist where resource-first names are used (person_colleagues, company_current_employees, company_hiring_signals), but they still follow an obvious and predictable pattern.

    Tool Count4/5

    Nineteen tools is on the heavier side, but the count is justified by the server's breadth: people, companies, signals, account utilities, and webhook monitoring. Each tool maps to a distinct operation and none feel redundant.

    Completeness4/5

    The surface covers the core workflow well: check existence, search, enrich single/bulk, and related people/company insights, plus monitor create/list/delete. The only notable gap is the lack of an update_monitor endpoint, but this can be worked around with delete and recreate.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Connect e-commerce and marketing data to AI assistants via MCP.

      https://mcp.presso.now/mcp
    • MCP server for LeadDelta — manage LinkedIn connections and CRM data via AI assistants.

      https://mcp.leaddelta.com/mcp
    • Search companies, enrich contacts, and reveal emails and phones from your AI agent.

      https://mcp.fiber.ai/mcp
    • Your agent needs B2B contacts and the pipeline objects around them — find the company, find the person, get the email, then write it back where your team works. **What you can ask for** • "Find heads of engineering at Series-B SaaS companies in the Nordics, with emails." • "Enrich these companies with headcount, industry and funding." • "What roles is this company hiring for right now?" • "Create an account and a contact, then log this opportunity." • "Search our sequences for messages sent to this domain." **How to use it** Point any MCP client at https://mcp.aisa.one/apollo/mcp and sign in with OAuth — there is no key to create or paste. 54 tools: people and organisation search and enrichment, job postings, accounts, contacts, opportunities and their stages, custom fields, labels, notes, users, email accounts, sequence messages and phone-call search — reads and writes. **Why this rather than the source** The full object model, not just a search endpoint, so an agent can finish the job rather than hand you a CSV. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the person here, then ask the same agent what their company's traffic looks like or what they rank for — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp adds Similarweb and creator discovery around it.

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Give your AI agent access to 60M+ companies and 300M+ verified contacts. Enrich leads, find work emails, discover tech stacks, and identify buying intent — directly from Claude, Cursor, Windsurf, or any MCP-compatible AI agent.
      11
      9 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables searching over 1 million enriched job listings from 20,000+ companies directly from MCP-compatible AI tools. Provides tools for job search, company profiles, and AI-powered similar job recommendations with real-time data updates.
      4
      102 npm
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Allows searching and enriching companies, people, job postings, and social posts via the DataForB2B API, bringing lead generation and market intelligence into MCP-compatible clients like Cursor and Claude.
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to discover and enrich real-time B2B company data, including contact details, ratings, websites, and emails, through MCP-compatible clients.
      5
      71 npm
      MIT