Skip to main content

​
CLI Guide

​
Advanced Routing & Service Composition

One of the most powerful features of the Cogni+ CLI is its ability to create sophisticated routing configurations between local and remote MCP services. This enables advanced use cases that wouldn’t be possible with either local-only or cloud-only solutions.

​
Routing between Local and Remote Services

The CLI can establish secure tunnels that allow seamless communication between services running in different environments: 
# Expose a local MCP server (running on port 8080) to Cogni+ cloud
cogni tunnel create --local http://localhost:8080 --name my-local-service
Once a tunnel is established, your local service can be accessed by remote agents or other services in the Cogni+ ecosystem.

​
Service Composition

The CLI enables you to compose complex workflows by combining local and remote MCP servers: 
# Create a service composition using both local and remote services
cogni compose create --name my-workflow \
  --services "local://my-database-tool,remote://cogni/web-search,remote://cogni/code-generator" \
  --output my-composition.json
This creates a composition configuration that routes requests to the appropriate services based on the requested tool.

​
Use Cases for Advanced Routing

​
Local Development with Remote Dependencies

When developing an MCP server that depends on other tools (like a web search tool), you can route only the dependency requests to remote services: 
# Start a development server that routes specific tool requests to remote services
cogni server dev --route-tools "web-search:remote://cogni/web-search,image-generation:remote://cogni/dalle"
This allows you to focus on developing your specific tool while seamlessly integrating with existing remote tools.

​
Privacy-Sensitive Operations

For operations involving sensitive data that shouldn’t leave your machine: 
# Create a secure workflow that keeps sensitive data local
cogni workflow create --config workflow.yaml
Example workflow.yaml: 
name: "Secure Document Processing"
tools:
  - id: "document-extraction"
    type: "local"  # Runs locally to keep documents secure
    path: "./document-tool"
  - id: "sentiment-analysis"
    type: "remote"
    server: "cogni/sentiment"
    # Only anonymized data will be sent to this remote service

​
Enhanced Agent Capabilities

Combine the power of multiple specialized MCP servers into a unified agent experience: 
# Start an agent that can use tools from multiple sources
cogni agent start --tools-local "./coding-tool,./file-access" --tools-remote "cogni/web-search,cogni/image-gen"

​
Real-Time Service Management

The CLI provides commands to monitor and manage your routing configurations: 
# List all active tunnels and compositions
cogni tunnel list

# View routing statistics and performance
cogni tunnel stats my-tunnel

# Update routing configuration
cogni tunnel update my-tunnel --rate-limit 100

​
Security Considerations

When using advanced routing features, consider these security best practices:
  • Authentication: All tunneled connections require proper authentication
  • Data Filtering: Configure data transformers to sanitize sensitive information before it leaves your local environment
  • Access Control: Use scoped access tokens to limit what remote services can access through your tunnels
  • Audit Logging: Enable detailed logs to track all cross-environment requests
# Enable secure audit logging for tunnels
cogni tunnel create --local http://localhost:8080 --name secure-tunnel --audit-log-level detailed

​
Advanced Configuration

For more complex routing scenarios, you can create a configuration file: 
# routing.yaml
tunnels:
  - name: data-processing-tunnel
    local: http://localhost:8080
    rate_limit: 100
    allowed_tools: ["query_database", "transform_data"]
    transforms:
      - type: pii_filter
        fields: ["email", "phone", "address"]
  
  - name: ai-generation-tunnel
    remote: cogni/text-generator
    local_cache: true
    timeout: 30s
Load this configuration with: 
cogni routing apply --config routing.yaml
By mastering these advanced routing capabilities, you can create sophisticated AI workflows that leverage both the security and control of local development with the scale and breadth of cloud services.