MCP & Tool Integration

📋Learning Objectives

• Understand MCP (Model Context Protocol) and its role in AI agent architectures
• Learn MCP primitives: Tools, Resources, and Prompts
• Understand how Loopback MCP auto-generates tools from ServiceConfigs
• Configure MCP Gateway for secure, authorized tool access
• Make tool discovery and invocation requests via JSON-RPC
• Integrate MCP tools in Experience plugins

🔌What is MCP?

The Model Context Protocol (MCP) is an open standard that defines how AI models interact with external tools, resources, and prompts. Think of it as a universal adapter that lets any AI agent (Claude, GPT, local models) discover and use tools without custom integrations.

Why MCP Matters

🏗️EmpowerNow MCP Architecture

EmpowerNow implements MCP with multiple server types that AI agents can connect to through a central gateway.

Key Components

🔄Loopback MCP

Loopback MCP is EmpowerNow's magic: it automatically converts your ServiceConfigs connectors and workflows into MCP tools that any AI agent can discover and invoke.

How Tools Are Generated

Tool Naming Convention

Tool Schema Example

Each tool exposes a JSON schema describing its inputs and outputs:

{
  "name": "entra.prod.user.create",
  "description": "Create a new user in Entra ID (Azure AD)",
  "inputSchema": {
    "type": "object",
    "properties": {
      "display_name": {
        "type": "string",
        "description": "User's display name"
      },
      "user_principal_name": {
        "type": "string",
        "description": "UPN (e.g., user@domain.com)"
      },
      "mail_nickname": {
        "type": "string",
        "description": "Mail alias"
      },
      "department": {
        "type": "string",
        "description": "Department name"
      }
    },
    "required": ["display_name", "user_principal_name", "mail_nickname"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "id": { "type": "string" },
      "user_principal_name": { "type": "string" },
      "created_date_time": { "type": "string" }
    }
  }
}

🛡️MCP Gateway

The MCP Gateway is the security perimeter for all MCP traffic. Every tool invocation passes through it for authentication and authorization.

Authorization Rules

PDP policies control which users/agents can invoke which tools:

# Example PDP policy for MCP tools
applications:
  mcp-tools:
    resources:
      tool:
        actions:
          - invoke
        rules:
          # Allow admins to invoke any tool
          - effect: permit
            condition: subject.roles contains "admin"
          
          # Allow helpdesk to invoke user tools only
          - effect: permit
            condition: |
              subject.roles contains "helpdesk" and
              resource.id starts_with "entra.prod.user"
          
          # Deny by default
          - effect: deny

📡JSON-RPC Protocol

MCP uses JSON-RPC 2.0 for communication. Here are the key methods:

Tool Discovery

# List all available tools
curl -X POST https://bff.self.empowernow.ai/api/crud/mcp/jsonrpc \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "tools/list",
    "params": {}
  }'

# Response
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "tools": [
      {
        "name": "entra.prod.user.create",
        "description": "Create a new user in Entra ID",
        "inputSchema": { ... }
      },
      {
        "name": "workflow.access_request",
        "description": "Submit an access request workflow",
        "inputSchema": { ... }
      }
    ]
  }
}

Tool Invocation

# Invoke a tool
curl -X POST https://bff.self.empowernow.ai/api/crud/mcp/jsonrpc \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-002",
    "method": "tools/call",
    "params": {
      "name": "workflow.access_request",
      "arguments": {
        "resource_id": "resource-123",
        "justification": "Need access for Q4 project",
        "duration": "7d"
      }
    }
  }'

# Response
{
  "jsonrpc": "2.0",
  "id": "req-002",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Workflow started: run-abc123"
      }
    ],
    "isError": false
  }
}

Progressive Tool Discovery

For large tool catalogs, use progressive discovery to reduce token usage:

# Step 1: List domains (minimal tokens)
{
  "method": "tools/call",
  "params": {
    "name": "registry.list_domains",
    "arguments": { "minimal": true }
  }
}

# Step 2: List tools in a domain
{
  "method": "tools/call",
  "params": {
    "name": "registry.list_tools",
    "arguments": {
      "domain": "identity-tools",
      "detail": "descriptions"  // minimal | descriptions | full
    }
  }
}

# Step 3: Get full schema for specific tool
{
  "method": "tools/call",
  "params": {
    "name": "registry.get_tool_schema",
    "arguments": { "tool_id": "entra.prod.user.create" }
  }
}

🔧Plugin SDK Integration

Experience plugins can invoke MCP tools through the SDK:

Using sdk.mcp

// src/hooks/useMcpTool.ts
const sdk = (globalThis as any).pluginSdk;

export async function listTools(): Promise<McpTool[]> {
  const response = await sdk.api.fetch('/api/crud/mcp/tools/list');
  const data = await response.json();
  return data.tools;
}

export async function invokeTool(
  toolName: string,
  args: Record<string, any>
): Promise<McpResult> {
  const response = await sdk.api.fetch('/api/crud/mcp/jsonrpc', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: crypto.randomUUID(),
      method: 'tools/call',
      params: {
        name: toolName,
        arguments: args
      }
    })
  });
  
  const result = await response.json();
  
  if (result.error) {
    throw new Error(result.error.message);
  }
  
  return result.result;
}

Tool Selector Component

// src/components/ToolSelector.tsx
const React = (globalThis as any).React;
const { useState, useEffect } = React;

interface McpTool {
  name: string;
  description: string;
  inputSchema: object;
}

export function ToolSelector({ onSelect }: { onSelect: (tool: McpTool) => void }) {
  const [tools, setTools] = useState<McpTool[]>([]);
  const [loading, setLoading] = useState(true);
  const [filter, setFilter] = useState('');

  useEffect(() => {
    listTools()
      .then(setTools)
      .catch(console.error)
      .finally(() => setLoading(false));
  }, []);

  const filtered = tools.filter(t =>
    t.name.toLowerCase().includes(filter.toLowerCase()) ||
    t.description.toLowerCase().includes(filter.toLowerCase())
  );

  if (loading) return <div>Loading tools...</div>;

  return (
    <div>
      <input
        type="text"
        placeholder="Filter tools..."
        value={filter}
        onChange={(e) => setFilter(e.target.value)}
      />
      <ul>
        {filtered.map(tool => (
          <li key={tool.name} onClick={() => onSelect(tool)}>
            <strong>{tool.name}</strong>
            <span>{tool.description}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

permissions:
  api:
    - method: GET
      path: /api/crud/mcp/tools/list
    - method: POST
      path: /api/crud/mcp/jsonrpc

👁️Virtual Views & Scoped Discovery

For large tool catalogs, Virtual Views filter tools by provider, tenant, or tags. Instead of listing all tools, agents can discover only what's relevant.

View Endpoints

Defining Virtual Views

# ServiceConfigs/CRUDService/config/mcp_virtual_servers.yaml
virtual_servers:
  - name: "entra"
    path_prefix: "/entra"
    filters:
      source: ["system"]
      provider: ["entra"]
  
  - name: "workflows"
    path_prefix: "/workflows"
    filters:
      source: ["workflow"]
  
  - name: "prompts"
    path_prefix: "/prompts"
    filters:
      source: ["prompt"]
  
  - name: "ad"
    path_prefix: "/ad"
    filters:
      source: ["system"]
      provider: ["ad", "ldap"]

View-Scoped JSON-RPC Example

# List only Entra tools (fewer tokens for AI)
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{"limit":50}}' \
  https://bff.self.empowernow.ai/api/crud/mcp/entra/jsonrpc

# Invoke a tool within the entra view
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":"2","method":"tools/call",
    "params": {
      "name":"entra.cont.account.get_by_id",
      "arguments":{"SystemIdentifier":"00000000-0000-0000-0000-000000000000"}
    }
  }' \
  https://bff.self.empowernow.ai/api/crud/mcp/entra/jsonrpc

📝MCP Prompts

Prompts are pre-built prompt templates that return messages for AI agents. They don't execute anything—they plan and explain, while workflows do the actual work.

Prompts vs Tools vs Workflows

Prompt Definition

# ServiceConfigs/CRUDService/config/prompts/identity_onboard.yaml
name: identity.onboard
title: "Onboard New Identity"
description: "Plan the onboarding of a new user across identity systems"
arguments:
  - name: email
    description: "User's email address"
    required: true
  - name: targets
    description: "Target systems (entra, ad, ldap)"
    required: false
    default: ["entra"]
messages:
  - role: system
    content: |
      You are an identity provisioning assistant.
      Create a Plan IR for onboarding {{ email }} to {{ targets }}.
      Always include an approval step for new account creation.
  - role: user
    content: |
      Please create an onboarding plan for {{ email }}.

Using Prompts via JSON-RPC

# List available prompts
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"prompts/list"}' \
  https://bff.self.empowernow.ai/api/crud/mcp/jsonrpc

# Get a prompt with arguments (returns rendered messages)
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":"2","method":"prompts/get",
    "params": {
      "name": "identity.onboard",
      "arguments": {
        "email": "jane.doe@example.com",
        "targets": ["entra", "ad"]
      }
    }
  }' \
  https://bff.self.empowernow.ai/api/crud/mcp/jsonrpc

🔐Authentication & Scopes

MCP endpoints require OAuth tokens with specific scopes.

Required Scopes

BFF MCP Proxy

The BFF proxies MCP requests and exempts them from CSRF/DPoP requirements:

# BFF MCP routes (prefix: /api/crud/mcp)
POST /api/crud/mcp/jsonrpc              # JSON-RPC to global view
POST /api/crud/mcp/{view}/jsonrpc       # JSON-RPC to specific view
GET  /api/crud/mcp/{view}/jsonrpc       # SSE bridge for Cursor/streamable clients

Cursor IDE Configuration

To use EmpowerNow MCP from Cursor IDE, create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "crud-mcp": {
      "type": "streamable-http",
      "url": "https://bff.self.empowernow.ai/api/crud/mcp/jsonrpc",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN_WITH_mcp_scopes>",
        "Content-Type": "application/json"
      }
    }
  }
}

Then in Cursor, open the MCP tools panel, enable crud-mcp, and ask: "List tools from crud-mcp."

📚Tool Catalogue Behavior

The Tool Catalogue is automatically built at startup and refreshes when configurations change.

Catalogue Sources

• Built-ins: From config/tools.yaml
• Loopback MCP: Auto-generated from ServiceConfigs (systems + workflows)
• External MCP: Discovered from config/mcp_endpoints.yaml

Auto-Refresh Triggers

The catalogue refreshes automatically when you:

• Create, update, or delete a system definition (/config/systems/*)
• Create, update, or delete a workflow (/workflows/*)
• Replace the tools config (PUT /config/tools)
• Add or modify prompts (/config/prompts/*)

Environment Variables

🔍Troubleshooting

Tool Not Found

Symptom: {"error": {"code": -32601, "message": "Tool not found: xyz"}}

Causes & Fixes:

• Tool name typo: Use tools/list to verify exact tool names
• Connector not configured: Check ServiceConfigs for the connector definition
• Tool filtered by PDP: The tool may exist but you lack permission to see it

403 Forbidden on Tool Invocation

Symptom: {"error": {"code": 403, "message": "Access denied"}}

Debug:

# Check PDP evaluation directly
curl -X POST https://pdp.self.empowernow.ai/access/v1/evaluation \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "user", "id": "current" },
    "resource": { "type": "tool", "id": "entra.prod.user.create" },
    "action": { "name": "invoke" },
    "context": { "reason_admin": true }
  }'

Invalid Arguments Error

Symptom: {"error": {"code": -32602, "message": "Invalid params"}}

Fix: Fetch the tool schema and validate your arguments match the inputSchema:

# Get full tool schema
{
  "method": "tools/call",
  "params": {
    "name": "registry.get_tool_schema",
    "arguments": { "tool_id": "your-tool-name" }
  }
}

MCP Server Unreachable

Symptom: {"error": {"code": -32603, "message": "Internal error"}}

Debug:

# Check MCP server health
curl https://bff.self.empowernow.ai/api/crud/health

# Check Gateway logs
docker logs mcp-gateway --tail 100

❓Knowledge Check

const response = await sdk.api.fetch('/api/crud/mcp/jsonrpc', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: crypto.randomUUID(),
    method: 'tools/call',
    params: { name: 'workflow.access_request', arguments: {...} }
  })
});

📝Day 21 Checkpoint

• Understand MCP's role in AI agent tool integration
• Know the three MCP primitives (Tools, Resources, Prompts)
• Understand how Loopback MCP auto-generates tools from ServiceConfigs
• Know the tool naming convention (provider.instance.entity.action)
• Understand MCP Gateway's authorization role
• Can discover tools using tools/list
• Can invoke tools using tools/call