Skip to main content

Integration

io.Intelligence Working Context offers two distinct integration approaches, each designed for specific use cases and architectural patterns. This guide helps you choose the right integration method and implement it effectively.

Integration Paths

Working Context can be used directly in applications or exposed through io.Intelligence MCP.

The two approved approaches remain the same. This page now introduces them with the same concise visual framing used elsewhere in the Modules section before moving into the full implementation guidance.

Integration Paths at a Glance​

Standalone usage

Use the API directly when you want full control over context retrieval, subscriptions, and custom application behavior.

MCP integration

Expose Working Context through the io.Intelligence MCP Server when protocol-level context access fits your architecture.

Decision support

Use the comparison, limitations, and decision guide sections below to choose the right approach for your system.

Implementation examples

Follow the included code samples and industry examples to adapt each approach to real-world application scenarios.

Integration Options Overview​

ApproachBest ForKey Benefits
Standalone UsageCustom implementations requiring direct controlFull API access, maximum flexibility
MCP Integrationio.Intelligence MCP solutionsProtocol-level exposure, lightweight

Standalone Usage​

Use Working Context directly via its API when building custom solutions that require direct control over context management without LLM integration.

When to Use Standalone
  • Custom context management solutions
  • Applications that need context data but don't use LLMs
  • Prototyping and testing context configurations
  • Building custom integrations with other systems

Implementation​

standalone-context.ts
import { IoIntelWorkingContextFactory } from "@interopio/working-context";
import IOConnectBrowser from "@interopio/browser";

async function initializeContext() {
  // Initialize io.Connect
  const io = await IOConnectBrowser();

  // Configure context schema
  const config = {
    schema: {
      clientId: {
        type: "string",
        description: "Currently selected client ID",
        source: {
          context: {
            location: {
              global: { names: ["ClientContext"] },
            },
            path: "client.id",
          },
        },
      },
      portfolioName: {
        type: "string",
        description: "Active portfolio name",
        source: {
          context: {
            location: {
              workspace: { target: "my" },
            },
            path: "portfolio.name",
          },
        },
      },
      selectedInstrument: {
        type: "object",
        description: "Currently selected trading instrument",
        source: {
          context: {
            location: {
              channel: { target: "my" },
            },
            path: "instrument",
          },
        },
      },
    },
  };

  // Create Working Context instance
  const workingContext = await IoIntelWorkingContextFactory(io, config);

  // Get current context
  const currentContext = workingContext.get();
  console.log("Client ID:", currentContext.clientId?.value);
  console.log("Portfolio:", currentContext.portfolioName?.value);

  // Subscribe to context changes
  const unsubscribe = workingContext.onChanged((updatedContext) => {
    console.log("Context updated:", updatedContext);

    // Process context updates
    if (updatedContext.clientId?.value) {
      handleClientChange(updatedContext.clientId.value);
    }

    if (updatedContext.selectedInstrument?.value) {
      handleInstrumentChange(updatedContext.selectedInstrument.value);
    }
  });

  // Later: unsubscribe when no longer needed
  // unsubscribe();

  return workingContext;
}

function handleClientChange(clientId: string) {
  // Custom logic for client changes
  console.log(`Client changed to: ${clientId}`);
}

function handleInstrumentChange(instrument: any) {
  // Custom logic for instrument changes
  console.log(`Instrument changed to: ${instrument.symbol}`);
}

Capabilities​

FeatureDescription
Direct API AccessFull control over context retrieval and updates
Custom ProcessingImplement your own logic for context changes
Flexible IntegrationIntegrate with any system or framework
LightweightNo LLM overhead if AI features aren't needed

Limitations​

Standalone Limitations
  • No automatic LLM integration
  • Requires manual context formatting for AI applications
  • No pre-built prompt templates
  • Developer manages all context processing

Integration with MCP​

This integration exposes Working Context through the io.Intelligence MCP Server implementation. This is designed for solutions using the io.Intelligence MCP infrastructure.

io.Intelligence MCP Required

This integration works exclusively with the io.Intelligence MCP Server implementation. It is not compatible with other MCP server implementations. Working Context is integrated directly into the io.Intelligence MCP Server and exposed as a built-in tool.

When to Use MCP Integration
  • io.Intelligence MCP-only implementations
  • Custom MCP client applications using io.Intelligence MCP
  • Systems requiring protocol-level context access
  • Lightweight integrations with io.Intelligence MCP infrastructure

Benefits​

BenefitDescription
Protocol-Level ExposureContext available as standard MCP tool
LightweightMinimal dependencies beyond MCP infrastructure
Flexible Prompt EngineeringFull control over LLM system prompts
Custom ImplementationDeveloper controls how context is used

Implementation​

mcp-core-integration.ts
import { IoIntelMCPCoreFactory } from "@interopio/mcp-core";
import { IoIntelWorkingContextFactory } from "@interopio/working-context";
import IOConnectBrowser from "@interopio/browser";

async function initializeMCPServer() {
  const io = await IOConnectBrowser();

  // Configure Working Context
  const contextConfig = {
    schema: {
      userId: {
        type: "string",
        description: "Current user identifier",
        source: {
          context: {
            location: {
              global: { names: ["UserSession"] },
            },
            path: "user.id",
          },
        },
      },
      activeWorkspace: {
        type: "object",
        description: "Current workspace information",
        source: {
          context: {
            location: {
              workspace: { target: "my" },
            },
            path: "workspace.metadata",
          },
        },
      },
      channelData: {
        type: "object",
        description: "Active channel context data",
        source: {
          context: {
            location: {
              channel: { target: "my" },
            },
            path: "data",
          },
        },
      },
    },
  };

  // Initialize MCP Core with Working Context
  const mcpApi = await IoIntelMCPCoreFactory(io, {
    licenseKey: process.env.IO_LICENSE_KEY!,
    transport: { type: "web" },
    server: {
      name: "context-aware-mcp",
      title: "Context-Aware MCP Server",
      tools: {
        system: {
          searchApps: { enabled: true },
          startApps: { enabled: true },
        },
      },
    },
    // Provide Working Context configuration
    context: {
      factory: IoIntelWorkingContextFactory,
      config: contextConfig,
    },
  });

  // Create MCP instance
  const { instance } = mcpApi.createMCPInstance({
    sampling: {},
    elicitation: {},
  });

  console.log("MCP server initialized with working context tool");

  return mcpApi;
}

The Working Context Tool​

When Working Context is configured, MCP automatically registers the io_connect_get_working_context tool.

Tool Output Structure:

{
  workingContext: {
    userId: {
      description: "Current user identifier",
      value: "user-12345"
    },
    activeWorkspace: {
      description: "Current workspace information",
      value: {
        name: "Trading Floor",
        layout: "grid"
      }
    },
    channelData: {
      description: "Active channel context data",
      value: {
        instrument: { symbol: "AAPL", type: "stock" }
      }
    }
  }
}

Custom Prompt Engineering​

Developer Responsibility

When using the MCP integration approach, you must engineer LLM system prompts to utilize context effectively.

const systemPrompt = `
You are an intelligent assistant with access to the user's working context.

You can retrieve the user's current business context using the io_connect_get_working_context tool.
This provides information about:
- Current user identity and profile
- Active workspace and layout
- Selected business objects (clients, instruments, portfolios, etc.)
- Channel data and shared context

Always check the working context when the user asks questions about:
- "What am I looking at?"
- "Who is the current client?"
- "What's in my workspace?"
- Anything related to their current business environment

Example usage:
User: "What client am I working with?"
1. Call io_connect_get_working_context
2. Extract relevant client information from the context
3. Provide a clear, helpful answer

Remember to interpret context properties based on their descriptions.
`;

Client Capability Handling​

The working context tool is automatically hidden if the MCP client declares experimental.workingContext capability, allowing clients to implement their own context handling:

// Client declares it handles context itself
const { instance } = mcpApi.createMCPInstance({
  sampling: {},
  elicitation: {},
  experimental: {
    workingContext: true, // Tool will not be registered
  },
});

Limitations​

MCP Integration Limitations
  • Manual Prompt Engineering — Developer must craft effective system prompts
  • No Automatic Integration — Context not automatically injected into conversations
  • Tool-Based Access — LLM must explicitly invoke tool to retrieve context
  • No Context Optimization — Developer responsible for context size and relevance

Best Practices for MCP Integration​

Best PracticeDescription
Clear System PromptsProvide explicit instructions for when and how to use the context tool
Context AwarenessEducate the LLM about what context properties mean
Tool Usage PatternsDefine clear patterns for context retrieval in prompts
Error HandlingHandle cases where context sources are unavailable
TestingThoroughly test the LLM's ability to retrieve and use context appropriately

Decision Guide​

Choose Standalone Usage If:​

  • You need context data without LLM integration
  • Building custom context processing logic
  • Prototyping or testing configurations
  • Integrating with non-AI systems

Choose MCP Integration If:​

  • Using io.Intelligence MCP infrastructure
  • Need protocol-level context exposure
  • Want full control over prompt engineering
  • Building custom MCP client applications with io.Intelligence MCP

Industry Examples​

Trading Application​

Track trader profile (global), active instrument (workspace), market data (channel), and open orders (app instance) simultaneously:

const tradingContextConfig = {
  schema: {
    // User profile from global context
    traderId: {
      type: "string",
      description: "Trader identifier",
      source: {
        context: {
          location: { global: { names: ["TraderProfile"] } },
          path: "trader.id",
        },
      },
    },
    traderRole: {
      type: "string",
      description: "Trader role and permissions",
      source: {
        context: {
          location: { global: { names: ["TraderProfile"] } },
          path: "trader.role",
        },
      },
    },

    // Active instrument from workspace
    activeInstrument: {
      type: "object",
      description: "Currently selected trading instrument",
      source: {
        context: {
          location: { workspace: { target: "my" } },
          path: "instrument",
        },
      },
    },

    // Market data from channel
    marketData: {
      type: "object",
      description: "Real-time market data feed",
      source: {
        context: {
          location: { channel: { target: "MarketData" } },
          path: "data.current",
        },
      },
    },

    // Open orders from app instance
    openOrders: {
      type: "array",
      description: "List of open trading orders",
      source: {
        context: {
          location: { appInstance: { appNames: ["OrderManager"] } },
          path: "orders.open",
        },
      },
    },
  },
};

Healthcare Application​

Track clinician session (global), active patient (workspace), recent vitals (app instance), and medication list (channel):

const healthcareContextConfig = {
  schema: {
    clinicianId: {
      type: "string",
      description: "Current clinician identifier",
      source: {
        context: {
          location: { global: { names: ["ClinicianSession"] } },
          path: "clinician.id",
        },
      },
    },
    activePatient: {
      type: "object",
      description: "Currently selected patient information",
      source: {
        context: {
          location: { workspace: { target: "my" } },
          path: "patient",
        },
      },
    },
    recentVitals: {
      type: "object",
      description: "Most recent patient vital signs",
      source: {
        context: {
          location: { appInstance: { appNames: ["VitalsMonitor"] } },
          path: "vitals.latest",
        },
      },
    },
    medicationList: {
      type: "array",
      description: "Current patient medications",
      source: {
        context: {
          location: { channel: { target: "PatientData" } },
          path: "medications.active",
        },
      },
    },
  },
};

Next Steps​