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 plus 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