Customercare MCP Builder

CustomerCare MCP Server Builder

This skill guides you through building production-ready MCP (Model Context Protocol) servers for customer care agents. Follow the specifications and patterns documented below exactly. All reference implementations are in references/examples.md.

CRITICAL INSTRUCTIONS FOR AGENTS

0. Ask About Programming Language

Before starting any implementation, ASK the user:

"Which programming language would you like to use for this MCP server?"

• TypeScript
• Python

Both languages have complete reference implementations in references/examples.md. Use the chosen language to build the MCP server.

1. ALWAYS Provide Tool Summary First

Before writing any code, create a comprehensive summary of all tools to be implemented:

• List each tool with its name, purpose, and pattern type
• Identify which tools need widgets, confirmations, or chaining
• Specify authentication requirements
• Document context management needs

Example Summary Format:

Tools to Create:
1. get_account_balance - Direct Response pattern, no confirmation
2. transfer_money - Transaction pattern (two-step), confirmation widget
3. update_profile - Hybrid Response, requires authentication check
4. welcome - Welcome tool (required on ALL servers)
5. knowledge_search - RAG integration (if OpenSearch available)

2. ALWAYS Confirm Specifications Before Coding

For EACH tool, before writing code:

1. Review the relevant pattern from the Pattern Specifications section below
2. Present the specification to the user and ask:
   • "Should this tool use a transaction pattern with confirmation?"
   • "What widgets are needed (picker, form, confirmation)?"
   • "Should this be a direct response or hybrid response?"
3. Reference implementation examples in references/examples.md

DO NOT assume -- Always confirm with the user before implementing.

3. Welcome Tool is MANDATORY

Every MCP server MUST have a welcome tool. See the Welcome Tool pattern below.

Before creating the welcome tool, ASK the user:

1. Authentication Method: JWT-based auto-auth or credential verification (PIN, password)?
2. Welcome Message: What should it say? What tone?
3. Target Audience: Who are the users (customers, employees, partners)?
4. Schema Requirements: What user information needs to be collected?

Reference: See "Welcome & Authentication Tools" section in references/examples.md

4. Knowledge Tool -- Confirm OpenSearch Setup

Before implementing knowledge/RAG functionality, ASK:

1. "Do you have an OpenSearch instance already set up?"
2. "What indices/collections should be searched?"

If OpenSearch is NOT available, do NOT implement the knowledge tool.

Reference: See "Knowledge/RAG Tools" section in references/examples.md

5. Server Startup Code -- Follow Reference EXACTLY

Copy the server entry point from references/examples.md exactly. Key requirements:

• TypeScript: Use @modelcontextprotocol/sdk, express, pino with EXACT versions from references/examples.md
• Python: Use mcp>=1.0.0, starlette>=0.40.0, uvicorn>=0.30.0 with EXACT versions from references/examples.md
• MUST use StreamableHTTPServerTransport (no session validation) - DO NOT use SSE transport SSE is not supported
• Create per-request server instances based on customer authentication state

Folder Structure:

project/
├── src/
│   ├── index.ts (or main.py + server.py)
│   ├── globalStore.ts (or global_store.py)
│   ├── localStore.ts (or local_store.py)
│   ├── logger.ts (or logger.py)
│   ├── customerDatabase.ts (or customer_database.py)
│   ├── [tool_name].ts (or [tool_name].py)
│   └── [tool_name]Service.ts (or [tool_name]_service.py)
├── package.json (or pyproject.toml)
└── .env.example

6. Widget Definitions -- NO DEVIATIONS

Widget specifications MUST be followed exactly. See Widget Types Reference below.

7. Final Solution Must Be Error-Free and Executable

Before presenting final solution: validate all code against the pattern specifications below, verify widget definitions match the Widget Types Reference, ensure all imports are correct, and confirm startup scripts work.

Pattern Specifications

Transactions (Two-Step Confirmation)

When to use: Any sensitive or irreversible operation (money transfers, payments, cancellations, profile changes).

Pattern:

• Step 1 (prepare): Model-visible tool collects inputs via widgets, then shows confirmation widget. Stores transaction details in LOCAL store.
• Step 2 (confirm/cancel): Hidden tool (visibility: ['app']) processes user's explicit confirm or cancel action.

Key Rules:

• Model can NEVER auto-confirm transactions
• Generate unique transaction ID per transaction
• Store details in LOCAL store (Layer 3), not global store
• Verify ownership before executing
• Clean up local variable after processing

Naming convention: prepare_[action] and confirm_or_cancel_[action]

Confirm/cancel tool config:

config: {
  _meta: {
    ui: { visibility: ['app'] }  // Hidden from model -- only callable by UI widget
  }
}

Confirmation widget schema:

{
  type: 'confirmation',
  title: 'Confirm Transfer',
  confirmation_text: '## Confirm\n\n**Details...**',
  on_confirm: {
    tool: 'confirm_or_cancel_[action]',
    parameters: { transactionId, action: 'confirm' },
  },
  on_cancel: {
    tool: 'confirm_or_cancel_[action]',
    parameters: { transactionId, action: 'cancel' },
  },
}

⚠ Widget-only responses: Confirmation widgets (and other pure-widget steps like account pickers) often return only _meta with no content array. Your handle_call_tool must handle empty content gracefully — do not default to a fallback text when _meta is present. See server.py in references/examples.md.

Direct Response (Tool Responses to Users)

When to use: Financial amounts, regulatory-required info, dates, account numbers -- anything that must be exact with zero hallucination risk.

Pattern: Set annotations: { audience: ['user'] } on content blocks. Content goes directly to user, bypassing the LLM entirely.

return {
  content: [{
    type: 'text',
    text: `Balance: $${balance.toFixed(2)}`,
    annotations: { audience: ['user'] },
  }],
};

Tradeoff: Model does NOT see this content, so it cannot reason about it. Use hybrid response when model needs context.

Hybrid Response

When to use: When you need both exact data display AND model awareness for conversation flow.

Pattern: Two content blocks -- one for model (audience: ['assistant']), one for user (audience: ['user']). structuredContent is always visible to the model.

return {
  content: [
    { type: 'text', text: 'Payment history retrieved. Data displayed to user.', annotations: { audience: ['assistant'] } },
    { type: 'text', text: `**Payment History**\n\n${table}`, annotations: { audience: ['user'] } },
  ],
  structuredContent: paymentData,
};

Tool Chaining

When to use: Deterministic tool-to-tool calls without LLM reasoning (e.g., locked account -> agent handoff).

Pattern: Return _meta.nextTool with tool name and arguments.

return {
  content: [{ type: 'text', text: 'Account is locked.', annotations: { audience: ['user'] } }],
  _meta: {
    nextTool: {
      tool: 'request_agent_handoff',
      parameters: { reason: 'Locked account' },
    },
  },
};

Rules: Only for tool-to-tool chaining (not user input dependent). Client must implement depth limits (recommended: 5).

Three-Layer Context System

MCP tools have access to three layers of context:

Accessing context variables:

// TypeScript (McpServer high-level SDK) -- extra is passed automatically
const jwtToken = extra?._meta?.['com.ibm.orchestrate/context']?.jwtToken;
const threadId = extra?._meta?.['com.ibm.orchestrate/systemcontext']?.thread_id;
const locale = extra?._meta?.['com.ibm.orchestrate/systemcontext']?.locale;

# Python (low-level Server SDK) -- extract _meta from request context, NOT function parameters
ctx = server.request_context
extra = {}
if ctx and ctx.meta:
    extra['_meta'] = ctx.meta.model_dump()

jwt_token = extra.get('_meta', {}).get('com.ibm.orchestrate/context', {}).get('jwtToken')
thread_id = extra.get('_meta', {}).get('com.ibm.orchestrate/systemcontext', {}).get('thread_id')
locale = extra.get('_meta', {}).get('com.ibm.orchestrate/systemcontext', {}).get('locale')

⚠ Python low-level SDK: When using the low-level Server class (not McpServer), _meta is not passed as a function parameter to @server.call_tool() handlers. You must read it from server.request_context.meta.model_dump(). Passing _meta as a handler parameter will silently be None, causing thread_id lookups to fail. See server.py in references/examples.md for the correct pattern.

Critical: NEVER trust the model to provide authentication data. Always inject customerId from the store or extract from JWT.

Unique Tools Per User

Pattern: Create per-request MCP server instances with only the tools relevant to a customer's products/entitlements.

• Unauthenticated users: only welcome + handoff tools
• After auth: register product-specific tools based on customer profile
• Must declare resources capability and handle empty resources list
• Use registerToolsWithCustomerId wrapper to inject customerId from global store

See references/examples.md Section 2 (Server Core Infrastructure) for the complete implementation.

Welcome Tool

Requirements:

• _meta.welcomeTool: true designates automatic invocation at thread start
• Must be visibility: ['app'] (hidden from model)
• Empty inputSchema (no required arguments)
• Only ONE welcome tool invoked per thread, even across multiple servers
• Should execute quickly

After successful auth, signal tool refresh:

return {
  content: [{ type: 'text', text: 'Verified!', annotations: { audience: ['user'] } }],
  _meta: { refreshThreadCapabilities: threadId },
};

This triggers ALL MCP servers to refresh their tool/resources lists for the thread.

Authentication

Two approaches:

1. Client Authentication (recommended): JWT passed via context variables. Tool extracts and uses directly.
2. Agent Authentication (voice/IVR): PIN verification in-agent, stores customerId in global store, triggers refreshThreadCapabilities.

After successful auth:

1. Store customerId in global store: setGlobalVariable(threadId, 'customerId', profile.customerId)
2. Return _meta: { refreshThreadCapabilities: threadId }
3. Client refreshes tool lists from ALL MCP servers
4. Servers check for customerId and return authenticated tools

Agent Handoff

Pattern: Two-step user-controlled handoff:

1. Present options (realtime or callback) via options widget
2. Process choice -- for realtime, use transfer_to_live_agent extension

Extension schema:

_meta: {
  'com.ibm.orchestrate/extensions': {
    transfer_to_live_agent: {
      message_to_human_agent: "Context for the agent...",
      agent_available: "Please wait while I connect you.",
      agent_unavailable: "No agents online. Try again later.",
    }
  }
}

Knowledge/RAG Integration

• Conditional registration: only when OPENSEARCH_PASSWORD env var is set
• Returns both formatted text and structuredContent
• Configurable field mappings and query bodies via environment variables
• Uses neural/semantic search by default