Developer Documentation

Build on Nynch

42 MCP tools for AI agents to search contacts, manage deals, analyze relationships, and orchestrate multi-agent workflows.

https://crcrwtjzqzinfzokianr.supabase.co/functions/v1/mcp-server

Quick Start

Connect any MCP-compatible AI client to Nynch in three steps.

Get an API Key

In Nynch, go to Settings → MCP Server and create an API key. Choose a scope: read, read-write, or admin.

Configure Your Client

Add the Nynch MCP endpoint to your AI client's configuration. Pass your API key as a Bearer token in the Authorization header.

Start Calling Tools

Your AI client discovers available tools automatically via MCP. Ask it to search contacts, check your pipeline, or create tasks.

Authentication & Transport

Authentication

All requests require a Bearer token — either a Supabase JWT (for the Nynch app) or a scoped MCP API key (for external agents).

read — Search, browse, and retrieve data
read-write — Read + create, update, delete records
admin — Full access including agent orchestration

Transport

The MCP server uses JSON-RPC 2.0 over Streamable HTTP — the standard MCP transport.

POST — Send tool calls and receive results
GET /sse — Subscribe to real-time events via Server-Sent Events
Rate limit — 1,000 requests/hour per API key

Tool Catalog

42 tools across 4 categories. Your AI client discovers these automatically via the MCP tools/list method.

CRM Read — 10 tools

Search, browse, and retrieve CRM data

search_contacts

Search contacts by name, company, or tags.

querylimit

get_contact_context

Get full context for a contact: profile, interactions, activities, notes, and relationship network.

contact_id

search_deals

Search deals by title, stage, or company.

querystagelimit

get_deal_context

Get full deal context: details, stakeholders, learnings, coaching actions, and relationship network.

deal_id

search_deals_by_inactivity

Find deals with no recent activity — useful for follow-up nudges and stalled-deal alerts.

days_inactivestageinclude_closedlimit

get_pipeline_summary

Pipeline health overview: active deals, stage distribution, pending nudges, and upcoming calendar.

format

get_next_best_actions

AI-powered recommendations for what to do next based on your pipeline and relationships.

limit

list_buckets

List all buckets (lists/segments) with name, goal, contact count, and activity frequency.

include_inactive

get_bucket_contacts

Get all contacts assigned to a specific bucket.

bucket_idbucket_namelimit

get_bucket_game_queue

Get contacts waiting in the bucket game queue — pending contacts that need to be sorted.

statuslimit

CRM Write — 12 tools

Create, update, and manage CRM records

log_interaction

Record a contact interaction (call, email, meeting, note).

contact_idtypesummarysentiment

update_deal_stage

Move a deal to a new pipeline stage.

deal_idnew_stage

create_task

Create a task or action item linked to a contact or deal.

titledescriptioncontact_iddeal_iddue_date

create_note

Add a note to a contact (supports markdown).

contact_idcontent

create_contact

Create a new contact. Auto-links to existing company by domain.

nameemailtitlecompany_namecompany_domainlinkedin_urlphonelocationtagslead_source

update_contact

Update fields on an existing contact. Only provided fields are changed.

contact_idnameemailtitletags

add_contact_to_bucket

Add a contact to a bucket (list/segment).

contact_idbucket_namebucket_id

create_deal

Create a new deal in the pipeline.

titlestagecompany_idprimary_contact_idvaluecurrencyclose_date

create_company

Create a new company in the CRM.

namedomainindustryemployee_range

delete_contact

Soft-delete a contact by ID. Can be recovered.

contact_id

bulk_delete_contacts

Soft-delete multiple contacts matching a tag or ID list.

tagcontact_ids

update_commitment

Mark a commitment as completed or update its details.

commitment_idis_completedtitledue_date

Relationship Intelligence — 11 tools

AI-powered insights on relationships, deals, and pipeline health

get_authority_score

Get your authority score across 6 dimensions: positioning, differentiation, thought leadership, inbound signals, credibility, and content consistency.

get_commitments

Get commitments (promises/tasks) for a contact or deal with Say/Do tracking.

contact_iddeal_idstatus

get_buying_committee

Get the buying committee / stakeholder map for a deal with roles, influence, and sentiment.

deal_id

get_contact_signals

Get recent signals: job changes, company changes, LinkedIn activity, buying intent.

contact_idlimit

get_interaction_history

Full interaction timeline: emails, meetings, calls, activities — with direction and sentiment.

contact_idlimittype

get_relationship_score

5-factor relationship strength score: recency, frequency, reciprocity, depth, outcome.

contact_id

export_context_briefing

Export a full AI-ready context briefing for a contact or deal.

contact_iddeal_id

get_relationship_trends

Analyze relationship trends — is engagement growing, stable, or declining?

contact_id

get_at_risk_relationships

Find contacts whose relationship scores have dropped or who haven't been contacted recently.

limit

get_deal_intelligence

Synthesized deal health: velocity trend, stakeholder coverage, commitment follow-through, risk factors.

deal_id

get_weekly_briefing

Weekly summary: new interactions, relationship changes, deal movements, overdue commitments, recommended actions.

Agent Orchestration — 8 tools

register_agent

agent_namecapabilitiesdescriptionarchetypemetadata

list_agents

List all registered agents with status and capabilities.

status

agent_heartbeat

Send a heartbeat to confirm agent is alive.

agent_name

write_context

Write a key-value pair to the shared agent context store.

context_keyvaluenamespacettl_hours

read_context

Read from the shared agent context store. Supports prefix matching with trailing *.

context_keynamespace

create_handoff

Request another agent to perform a task. Routes by agent name or capability.

task_descriptionto_agent_nameto_capabilityinput_contextpriority

get_handoffs

Get pending handoffs assigned to this agent.

agent_namestatus

complete_handoff

Mark a handoff as completed (or failed) with results.

handoff_idstatusresulterror_message

MCP Resources

Resource templates for reading structured context directly.

nynch://contacts/{id}

Full contact context: profile, relationship score, recent interactions, notes, and network.

nynch://deals/{id}

Deal context: details, stakeholders, coaching actions, learnings, and relationship network.

nynch://pipeline/summary

Pipeline health overview: stage distribution, active value, at-risk deals, and upcoming closes.

Agent Orchestration

Run multiple AI agents that share context and hand off tasks to each other — all through the same MCP endpoint.

How It Works

Each agent registers with a name, capabilities, and archetype
Agents share state via a key-value context store with namespaces and TTLs
Tasks are routed by agent name or capability matching
Heartbeats track agent liveness; stale agents are flagged

Archetypes

Producer — Creates data (research, enrichment)
Consumer — Reads and acts on data (outreach, reporting)
Coordinator — Orchestrates other agents
Critic — Reviews and validates output

Code Examples

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "nynch": {
      "url": "https://crcrwtjzqzinfzokianr.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "nynch": {
      "url": "https://crcrwtjzqzinfzokianr.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Python — using the MCP SDK

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://crcrwtjzqzinfzokianr.supabase.co/functions/v1/mcp-server",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Search contacts
        result = await session.call_tool(
            "search_contacts", {"query": "Acme Corp"}
        )
        print(result)

Ready to build?

Create a free Nynch account, generate an API key, and start building in minutes.

Get Started Free