Agent-CoreX Documentation

Agent-CoreX Architecture

Agent-CoreX is built on three core pillars: Tool Retrieval, MCP Management, and Intelligent Execution. Let’s break down how everything works together.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          Your Application                       │
│              (Agent, Service, or Custom Workflow)               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                  ┌────────┴────────┐
                  │                 │
                  ↓                 ↓
          ┌──────────────┐  ┌──────────────┐
          │  /retrieve   │  │  /execute    │
          │   _tools     │  │   _tool      │
          └──────┬───────┘  └──────────────┘
                 │                 │
                 │                 └────────────────┐
                 │                                  │
        ┌────────┴────────┐                        │
        │                 │                        │
        ↓                 ↓                        ↓
    ┌────────────┐  ┌────────────┐  ┌──────────────────┐
    │ Tool Index │  │   Ranking  │  │ Query Events &   │
    │ (Vector    │  │   Engine   │  │ Observability    │
    │  DB)       │  │ (LLM)      │  │ (Logging)        │
    └────────────┘  └────────────┘  └────────┬────────┘
                                              │
                           ┌──────────────────┼──────────────────┐
                           │                  │                  │
        ┌──────────────────┼──────────────────┐                 │
        │                  │                  │                 │
        ↓                  ↓                  ↓                 ↓
    ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌─────────────────┐
    │GitHub MCP  │  │ Slack MCP  │  │  Jira MCP  │  │ Dashboard       │
    │Server      │  │Server      │  │Server      │  │ (Query History) │
    └────┬───────┘  └────┬───────┘  └────┬───────┘  └─────────────────┘
         │               │               │
         ↓               ↓               ↓
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │GitHub API  │  │ Slack API  │  │  Jira API  │
    └────────────┘  └────────────┘  └────────────┘

Core Components

1. Tool Retrieval Engine

The heart of Agent-CoreX. Converts natural language queries into ranked tool recommendations. How it works:

User/Agent queries: "I need to deploy to AWS and notify Slack"
Query is vectorized using embeddings
Matched against tool index (100+ MCP servers)
LLM-based ranker scores tools by relevance
Returns top-k tools sorted by relevance score

Key Features:

Fast semantic search (sub-50ms)
Context-aware ranking
Token-optimized responses
Caching for frequently queried patterns

2. MCP Manager

Routes tool execution requests to the appropriate MCP server and handles communication. Responsibilities:

Server discovery and health checks
Load balancing across MCP instances
Authentication & credential management
Error handling & retries
Response formatting

Supported Protocols:

JSON-RPC 2.0 (MCP standard)
REST with MCP gateway
WebSocket for real-time tools

3. Tool Index

A vector database that catalogs all available tools and their metadata. Contains:

Tool name, description, parameters
Input/output schemas
Authentication requirements
Performance metadata
Usage frequency & popularity

Updated:

Real-time when new MCP servers connect
Nightly indexing of tool changes
On-demand reindexing via API

4. Ranking & Optimization Engine

Uses LLM-based intelligence to rank tools and optimize token usage. Ranking Factors:

Semantic relevance (0.4 weight)
Tool popularity (0.25 weight)
User history (0.2 weight)
Performance metrics (0.15 weight)

Optimization:

Minimizes context window usage
Batches similar tools
Prunes low-confidence results
Caches hot tools

5. Query Events & Observability

Comprehensive logging and monitoring of tool retrieval patterns. Capabilities:

Logs all queries with rankings and selections
Tracks request source (CLI/MCP, API, Dashboard)
Records tool metadata and score details
Enables analytics and debugging via dashboard
Fire-and-forget logging (non-blocking)

Uses:

Monitor which tools agents select
Debug ranking issues
Analyze usage patterns
Track performance metrics
Audit trail for compliance

Learn more in Query Events & Observability

Data Flow: From Query to Execution

Let’s trace a real request:

Scenario: “Create a GitHub PR, update Jira, and notify Slack”

┌─────────────────────────────────────────────────────────────────┐
│ REQUEST: Agent says "Create a GitHub PR, update Jira, notify    │
│ Slack"                                                          │
└────────────────────────┬────────────────────────────────────────┘
                         │
        ┌────────────────┴──────────────────┐
        │                                   │
        ↓                                   ↓
   PHASE 1: RETRIEVAL              PHASE 2: RANKING
   ┌──────────────────────┐        ┌──────────────────────┐
   │1. Embed query        │        │1. LLM scores results │
   │2. Search vector DB   │        │2. Context filtering  │
   │3. Get candidates:    │        │3. Sort by relevance  │
   │   - create-pr        │        │                      │
   │   - create-issue     │        │ SCORED:              │
   │   - send-message     │        │ 0.98 create-pr       │
   │   - update-jira      │        │ 0.96 update-jira     │
   │   - slack-notify     │        │ 0.94 send-message    │
   │   (25 candidates)    │        │ (filtered to top 5)  │
   └──────────────────────┘        └──────────────────────┘
        │                                  │
        └──────────────┬───────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                             │
        ↓                             ↓
  PHASE 3: TOOL INFO            PHASE 4: EXECUTION
  ┌──────────────────────┐     ┌──────────────────────┐
  │Fetch tool schemas:   │     │1. Agent selects top  │
  │- Parameters          │     │   3 tools            │
  │- Descriptions        │     │2. MCP Manager routes │
  │- Auth requirements   │     │   to servers         │
  │                      │     │3. Parallel execution │
  │Return to Agent:      │     │4. Aggregate results  │
  │[                     │     │                      │
  │  {                   │     │ RESULTS:             │
  │    name: "create-pr" │     │ ✅ PR #123 created   │
  │    score: 0.98       │     │ ✅ Jira TASK-456     │
  │    params: {...}     │     │ ✅ Slack notified    │
  │  },                  │     │                      │
  │  ...                 │     │ Total time: 2.3s     │
  │]                     │     └──────────────────────┘
  └──────────────────────┘

MCP Servers for Developers: Integration

Agent-CoreX provides first-class support for MCP servers across developer ecosystems:

MCP Servers in AI Applications

Agent-CoreX integrates with:

├── Claude Ecosystem
│   ├── MCP Servers for Claude Code
│   ├── Claude API (native integration)
│   └── Claude Web Interface
│
├── VS Code Integration
│   ├── MCP Servers in VS Code
│   ├── VS Code Extension
│   └── Inline AI Assistance
│
├── GitHub Copilot
│   ├── MCP Servers for GitHub Copilot
│   ├── Copilot Chat
│   └── Code Completion
│
└── Enterprise Copilot
    ├── MCP Servers in Copilot
    ├── Custom Copilot instances
    └── Organization-wide access

Security & Authentication

Each MCP server connection is secured:

┌──────────────────────────────────────┐
│ User Connects MCP Server             │
│ (e.g., GitHub Personal Token)        │
└────────┬─────────────────────────────┘
         │
         ↓
┌──────────────────────────────────────┐
│ Encryption (AES-256)                 │
│ Stored in secure vault               │
└────────┬─────────────────────────────┘
         │
         ↓
┌──────────────────────────────────────┐
│ When Tool Executes:                  │
│ 1. Credential retrieved (decrypted)  │
│ 2. Injected into MCP call            │
│ 3. Sent to MCP server                │
│ 4. Credential immediately cleared    │
│ 5. No logs contain sensitive data    │
└────────┬─────────────────────────────┘
         │
         ↓
┌──────────────────────────────────────┐
│ Audit Trail                          │
│ ✓ Who executed                       │
│ ✓ Which tool                         │
│ ✓ Timestamp                          │
│ ✗ No credentials in logs             │
└──────────────────────────────────────┘

Performance Characteristics

Metric	Value	Notes
Tool Retrieval	15-50ms	Includes vectorization & ranking
Tool Execution	100ms-5s	Depends on external API
Max Tools Returned	50	Default: 5 (configurable)
Concurrent Requests	1,000/sec	Per authenticated user
Tool Index Size	100+ servers	Grows with MCP marketplace
Uptime SLA	99.99%	Enterprise tier

Deployment Topology

Agent-CoreX can be deployed in multiple configurations:

1. Cloud Managed (Default)

Your App → Agent-CoreX Cloud → MCP Servers

Pros: Zero maintenance, automatic scaling Cons: External dependency

2. Self-Hosted

Your App → Agent-CoreX (Self-Hosted) → MCP Servers

Pros: Full control, private deployment Cons: You manage infrastructure

3. Hybrid

Your App → Agent-CoreX (Private VPC) → Internal MCP + Cloud MCP

Pros: Best of both worlds Cons: More complex setup

Comparison: MCP Servers for Developers

Agent-CoreX simplifies working with MCP servers across different environments:

Feature	Manual MCP	Agent-CoreX
Tool Discovery	Manual	Automatic semantic search
Tool Selection	Hardcode	AI-powered ranking
Server Management	DIY	Built-in
Error Handling	Manual	Automatic retries
Monitoring	DIY	Built-in dashboards
MCP Servers in VS Code	Limited	Full marketplace access
MCP Servers for Claude Code	Setup required	One-click connect
Token Optimization	Manual	Automatic

Next Steps

Core Concepts

Learn about tool lifecycle and dynamic retrieval in detail.

MCP Setup

Connect your first MCP server and start building.

API Reference

Detailed endpoint documentation with examples.

Use Cases

See real-world examples of Agent-CoreX in action.

Want to understand the technical details? Check out our GitHub repository for source code and architecture discussions.

Home

Getting Started

Core Concepts

MCP Servers

Tool Retrieval System

Use Cases

Architecture Overview

Agent-CoreX Architecture

System Architecture

Core Components

1. Tool Retrieval Engine

2. MCP Manager

3. Tool Index

4. Ranking & Optimization Engine

5. Query Events & Observability

Data Flow: From Query to Execution

Scenario: “Create a GitHub PR, update Jira, and notify Slack”

MCP Servers for Developers: Integration

MCP Servers in AI Applications

Security & Authentication

Performance Characteristics

Deployment Topology

1. Cloud Managed (Default)

2. Self-Hosted

3. Hybrid

Comparison: MCP Servers for Developers

Next Steps

Core Concepts

MCP Setup

API Reference

Use Cases

​Agent-CoreX Architecture

​System Architecture

​Core Components

​1. Tool Retrieval Engine

​2. MCP Manager

​3. Tool Index

​4. Ranking & Optimization Engine

​5. Query Events & Observability

​Data Flow: From Query to Execution

​Scenario: “Create a GitHub PR, update Jira, and notify Slack”

​MCP Servers for Developers: Integration

​MCP Servers in AI Applications

​Security & Authentication

​Performance Characteristics

​Deployment Topology

​1. Cloud Managed (Default)

​2. Self-Hosted

​3. Hybrid

​Comparison: MCP Servers for Developers

​Next Steps

Core Concepts

MCP Setup

API Reference

Use Cases

Agent-CoreX Architecture

System Architecture

Core Components

1. Tool Retrieval Engine

2. MCP Manager

3. Tool Index

4. Ranking & Optimization Engine

5. Query Events & Observability

Data Flow: From Query to Execution

Scenario: “Create a GitHub PR, update Jira, and notify Slack”

MCP Servers for Developers: Integration

MCP Servers in AI Applications

Security & Authentication

Performance Characteristics

Deployment Topology

1. Cloud Managed (Default)

2. Self-Hosted

3. Hybrid

Comparison: MCP Servers for Developers

Next Steps