π¦
Agent Framewrok
This framework will combine multiple mcp servers required to create an agent
0 installs
Trust: 34 β Low
Devtools
Ask AI about Agent Framewrok
Powered by Claude Β· Grounded in docs
I know everything about Agent Framewrok. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
Agent Framework
A Spring Boot microservice for creating, managing, and executing AI agents with dynamic MCP (Model Context Protocol) tool integration.
Table of Contents
- Overview
- Architecture
- High Level Design (HLD)
- Low Level Design (LLD)
- Entity Relationship Diagram
- Sequence Diagrams
- MCP Tool Selection Strategies
- Module Structure
- API Reference
- Configuration
- Quick Start
Overview
The Agent Framework is a Java-based orchestration layer that:
- Creates AI agents dynamically based on natural language descriptions
- Discovers and integrates with MCP servers (Jira, Confluence, GitHub, Webex)
- Manages agent lifecycle with persistent storage in PostgreSQL
- Orchestrates execution by routing queries to downstream AI services
- Uses LLM intelligence for tool selection and argument building
Architecture
High Level Design (HLD)
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CLIENT LAYER β
β (REST API Clients / Web UI / CLI) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β API GATEWAY LAYER β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββββββββββ β
β β AgentCrudCtrl β β AgentExecCtrl β β ToolController β β
β β POST /agents β β POST /run β β GET /tools β β
β β GET /agents β β DELETE /session β β GET /tools/categories β β
β β DELETE /agents β β β β β β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β FACADE LAYER β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentFacade β β
β β β’ Orchestrates agent creation workflow β β
β β β’ Coordinates between services and data layer β β
β β β’ Handles deduplication logic β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β SERVICE LAYER β
β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββ β
β β MetaAgentSvc β β AgentCreation β β AgentExecutor β β
β β β’ Analyzes β β β’ Builds spec β β β’ Calls MCP β β
β β descriptions β β β’ Persists β β β’ Routes to β β
β β β’ Selects toolsβ β β’ Creates β β downstream β β
β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββ β
β β
β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββ β
β β LLMService β β ConfigDecider β β DownstreamSvc β β
β β β’ GPT/Claude β β β’ RAG config β β β’ Python agent β β
β β β’ Tool select β β β’ Reasoning β β β’ Session mgmt β β
β β β’ Arg building β β β’ Temperature β β β’ Run requests β β
β ββββββββββββββββββ ββββββββββββββββββ ββββββββββββββββββ β
β β
β ββββββββββββββββββ ββββββββββββββββββ β
β β MCPDiscovery β β MCPDataFetcher β β
β β β’ Discovers β β β’ Fetches data β β
β β tools at β β for config β β
β β startup β β decisions β β
β ββββββββββββββββββ ββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DATA LAYER β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentDataFacade β β
β β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββ β β
β β β AgentRepository β β McpToolRepositoryβ β MCPToolRegistry β β β
β β β (JPA/Postgres) β β (JPA/Postgres) β β (In-Memory Cache) β β β
β β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EXTERNAL SYSTEMS β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β β PostgreSQL β β MCP Servers β β Downstream β β LLM Providerβ β
β β Database β β Jira/GitHub β β Python AI β β GPT/Claude β β
β β β β Confluence β β Service β β Gemini β β
β β β β Webex β β β β β β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ βββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Component Descriptions
| Layer | Component | Responsibility |
|---|---|---|
| API | AgentCrudController | CRUD operations for agents |
| API | AgentExecutionController | Run agents, manage sessions |
| API | ToolController | List available MCP tools |
| Facade | AgentFacade | Orchestrate agent workflows |
| Service | MetaAgentService | Analyze descriptions, select tools |
| Service | AgentCreationService | Create agents with full config |
| Service | AgentExecutorService | Execute MCP tool calls |
| Service | LLMService | LLM integration for intelligence |
| Service | DownstreamAgentService | Communicate with Python AI |
| Service | MCPDiscoveryService | Discover tools from MCP servers |
| Data | AgentDataFacade | Abstract data operations |
| Data | MCPToolRegistry | In-memory tool cache |
Low Level Design (LLD)
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CONTROLLER CLASSES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentCrudController β β
β β @RestController @RequestMapping("/api/agents") β β
β β βββ POST / β createAgent(CreateAgentRequest) β β
β β βββ GET / β listAgents(ownerId, tenantId, status, ...) β β
β β βββ GET /{id} β getAgent(UUID) β β
β β βββ GET /{id}/config β getAgentConfig(UUID) β β
β β βββ DELETE /{id} β deleteAgent(UUID) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentExecutionController β β
β β @RestController @RequestMapping("/api/agents") β β
β β βββ POST /{id}/run β runAgentById(UUID, RunAgentRequest) β β
β β βββ DELETE /{id}/session β clearSession(UUID) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β ToolController β β
β β @RestController @RequestMapping("/api/tools") β β
β β βββ GET / β getTools() β β
β β βββ GET /categories β getToolCategories() β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β SERVICE CLASSES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentCreationService β β
β β βββ createAgent(CreateAgentRequest) β AgentCreationOutcome β β
β β β βββ buildAgentSpec() β β
β β β βββ normalizeTools() β β
β β β βββ handleExistingAgent() [deduplication] β β
β β β βββ fetchDecisionData() β β
β β β βββ decideConfig() β β
β β β βββ createDownstreamAgent() β Python service β β
β β β βββ persistNewAgent() β β
β β βββ Dependencies: MetaAgentService, MCPToolRegistry, LLMService, β β
β β ConfigDeciderService, DownstreamAgentService β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β MetaAgentService β β
β β βββ buildAgentSpec(CreateAgentRequest) β AgentSpec β β
β β β βββ buildAgentSpecWithLLM() [if LLM enabled] β β
β β β βββ buildAgentSpecWithKeywordAnalysis() [fallback] β β
β β βββ extractKeywords(text) β List<String> β β
β β βββ findMatchingTools(keywords, availableTools) β List<String> β β
β β βββ determineExecutionMode(description) β String β β
β β βββ determinePermissions(description) β List<String> β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AgentExecutorService β β
β β βββ executeAgent(AgentExecutionRequest) β AgentExecutionResponse β β
β β βββ callMcpTool(MCPTool, arguments) β Object β β
β β β βββ JSON-RPC for Jira/Confluence/GitHub β β
β β β βββ REST for Webex β β
β β βββ buildToolArguments(tool, request) β Map<String, Object> β β
β β βββ WebClients: jiraMcpClient, confluenceMcpClient, githubMcpClient β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β LLMService β β
β β βββ isEnabled() β boolean β β
β β βββ analyzeAgentDescription(name, desc, tools) β LLMAnalysisResult β β
β β βββ buildToolArguments(toolName, query, desc) β Map<String, Object> β β
β β βββ generateSystemPrompt(name, desc, tools) β String β β
β β βββ Providers: Cisco LLM Proxy, OpenAI, Anthropic, Gemini β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β DownstreamAgentService β β
β β βββ createAgent(DownstreamAgentCreateRequest) β Response β β
β β βββ getAgent(agentId) β DownstreamAgentDetailResponse β β
β β βββ listAgents(filters) β DownstreamAgentListResponse β β
β β βββ runAgent(DownstreamAgentRunRequest) β DownstreamAgentRunResponseβ β
β β βββ Session Management: β β
β β βββ getOrCreateSession(agentId) β β
β β βββ getActiveSession(agentId) β β
β β βββ isValidSession(agentId, sessionId) β β
β β βββ clearSession(agentId) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β MCPDiscoveryService β β
β β βββ @PostConstruct discoverTools() β β
β β β βββ discoverFromServer(category, url, token, isRestApi) β β
β β β βββ discoverFromJsonRpc() [Jira/Confluence/GitHub] β β
β β β βββ discoverFromRestApi() [Webex] β β
β β βββ parseAndRegisterTools(category, response) β β
β β βββ refresh() β Re-discover all tools β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DATA CLASSES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Entity: Agent β β
β β @Table(name = "agents") β β
β β βββ id: UUID (PK) β β
β β βββ name, description, goal: String β β
β β βββ allowedTools: String (unique, sorted comma-separated) β β
β β βββ agentSpec: TEXT (JSON) β β
β β βββ Configuration: ragScope, reasoningStyle, temperature, β β
β β β retrieverType, retrieverK, executionMode β β
β β βββ Downstream: downstreamStatus, downstreamAgentId β β
β β βββ mcpServers: List<AgentMcpServer> (OneToMany) β β
β β βββ Timestamps: createdAt, updatedAt β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Entity: AgentMcpServer β β
β β @Table(name = "agent_mcp_servers") β β
β β βββ id: UUID (PK) β β
β β βββ agent: Agent (ManyToOne, FK β agents.id) β β
β β βββ serverName: String β β
β β βββ createdAt: OffsetDateTime β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Entity: McpToolEntity β β
β β @Table(name = "mcp_tools") β β
β β βββ id: UUID (PK) β β
β β βββ name: String (unique) β β
β β βββ description, category: String β β
β β βββ capabilities: List<String> β β
β β βββ requiredInputs: List<String> β β
β β βββ Timestamps: createdAt, updatedAt β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β MCPToolRegistry (In-Memory Cache) β β
β β βββ ConcurrentHashMap<String, MCPTool> tools β β
β β βββ registerTool(MCPTool) β β
β β βββ getTool(name) β Optional<MCPTool> β β
β β βββ getAllTools() β List<MCPTool> β β
β β βββ getToolsByCategory(category) β List<MCPTool> β β
β β βββ ensureToolsPersisted(toolNames) β Sync to DB β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Entity Relationship Diagram
erDiagram
AGENTS ||--o{ AGENT_MCP_SERVERS : "has many"
AGENTS {
uuid id PK "Primary Key"
text name "Display name"
text description "What the agent does"
text goal "Agent's purpose"
text allowed_tools UK "Sorted comma-separated tools (unique)"
text agent_spec "Full AgentSpec as JSON"
text created_by "Who created the agent"
text tenant_id "Organization/workspace"
text rag_scope "Comma-separated RAG scopes"
text reasoning_style "direct, step-by-step, comparative"
decimal temperature "0.00 to 1.00"
text retriever_type "simple, multi-query, ensemble"
int retriever_k "Number of chunks to retrieve"
text execution_mode "static or dynamic"
text permissions "read_only, write, execute"
text system_prompt "Generated system prompt"
int max_steps "Max execution steps"
text brain_agent_id "ID from Python service"
text status "active, inactive, draft"
text downstream_status "Downstream creation status"
text downstream_agent_id "Downstream agent ID"
timestamptz created_at "Creation timestamp"
timestamptz updated_at "Last update timestamp"
}
AGENT_MCP_SERVERS {
uuid id PK "Primary Key"
uuid agent_id FK "Foreign Key to agents"
text server_name "jira, webex, confluence, github"
timestamptz created_at "Creation timestamp"
}
MCP_TOOLS {
uuid id PK "Primary Key"
text name UK "Tool name (unique)"
text description "Tool description"
text category "jira, confluence, github, webex"
text capabilities "Comma-separated capabilities"
text required_inputs "Comma-separated required inputs"
timestamptz created_at "Creation timestamp"
timestamptz updated_at "Last update timestamp"
}
Relationships
| Relationship | Type | Description |
|---|---|---|
AGENTS β AGENT_MCP_SERVERS | One-to-Many | An agent can use multiple MCP servers |
MCP_TOOLS | Standalone | Registry of all available MCP tools |
Key Constraints
agents.allowed_tools: UNIQUE constraint ensures one agent per tool combination (deduplication)agent_mcp_servers(agent_id, server_name): UNIQUE constraint prevents duplicate server assignmentsmcp_tools.name: UNIQUE constraint prevents duplicate tool registrations
Sequence Diagrams
1. Agent Creation Flow
sequenceDiagram
autonumber
participant Client
participant AgentCrudCtrl as AgentCrudController
participant AgentFacade
participant AgentCreationSvc as AgentCreationService
participant MetaAgentSvc as MetaAgentService
participant LLMService
participant MCPToolRegistry
participant ConfigDecider as ConfigDeciderService
participant DownstreamSvc as DownstreamAgentService
participant AgentDataFacade
participant PostgreSQL
participant PythonAI as Python AI Service
Client->>AgentCrudCtrl: POST /api/agents
Note right of Client: {name, description, ownerId, tenantId}
AgentCrudCtrl->>AgentFacade: createAgent(request)
AgentFacade->>AgentCreationSvc: createAgent(request)
%% Build Agent Spec
AgentCreationSvc->>MetaAgentSvc: buildAgentSpec(request)
alt LLM Enabled
MetaAgentSvc->>LLMService: analyzeAgentDescription(name, desc, tools)
LLMService-->>MetaAgentSvc: LLMAnalysisResult
else LLM Disabled
MetaAgentSvc->>MetaAgentSvc: buildAgentSpecWithKeywordAnalysis()
end
MetaAgentSvc-->>AgentCreationSvc: AgentSpec (selectedTools, goal, executionMode)
%% Ensure Tools in Registry
AgentCreationSvc->>MCPToolRegistry: ensureToolsPersisted(allowedTools)
%% Check for existing agent (deduplication)
AgentCreationSvc->>AgentDataFacade: existsByAllowedTools(allowedToolsKey)
AgentDataFacade->>PostgreSQL: SELECT * FROM agents WHERE allowed_tools = ?
alt Agent Exists
PostgreSQL-->>AgentDataFacade: Existing Agent
AgentDataFacade-->>AgentCreationSvc: true
AgentCreationSvc-->>Client: 200 OK (existing agent)
else Agent Not Found
PostgreSQL-->>AgentDataFacade: null
AgentDataFacade-->>AgentCreationSvc: false
%% Generate UUID for new agent
AgentCreationSvc->>AgentCreationSvc: Generate UUID (agentId)
%% Fetch MCP data for config decisions
AgentCreationSvc->>AgentCreationSvc: fetchDecisionData(tools)
%% Decide configuration
AgentCreationSvc->>ConfigDecider: decideConfig(agentSpec, mcpData, desc)
ConfigDecider-->>AgentCreationSvc: AgentConfigDto
%% Generate system prompt with LLM
AgentCreationSvc->>LLMService: generateSystemPrompt(name, desc, tools)
LLMService-->>AgentCreationSvc: systemPrompt
%% Create downstream agent in Python service
AgentCreationSvc->>DownstreamSvc: createAgent(payload)
DownstreamSvc->>PythonAI: POST /agents
PythonAI-->>DownstreamSvc: {agentId, status}
DownstreamSvc-->>AgentCreationSvc: DownstreamAgentCreateResponse
%% Persist to database
AgentCreationSvc->>AgentDataFacade: createAgentWithId(...)
AgentDataFacade->>PostgreSQL: INSERT INTO agents
AgentDataFacade->>PostgreSQL: INSERT INTO agent_mcp_servers
PostgreSQL-->>AgentDataFacade: Agent created
AgentDataFacade-->>AgentCreationSvc: AgentDto
AgentCreationSvc-->>Client: 201 Created (AgentCreateResponse)
end
2. Agent Execution Flow
sequenceDiagram
autonumber
participant Client
participant AgentExecCtrl as AgentExecutionController
participant AgentFacade
participant DownstreamSvc as DownstreamAgentService
participant SessionCache as Session Cache
participant PythonAI as Python AI Service
participant MCPServers as MCP Servers
Client->>AgentExecCtrl: POST /api/agents/{id}/run
Note right of Client: {query, userId, sessionId?, maxIterations, autoApprove}
%% Validate agent exists
AgentExecCtrl->>AgentFacade: findAgentById(agentId)
AgentFacade-->>AgentExecCtrl: AgentDto
%% Session management
AgentExecCtrl->>DownstreamSvc: getActiveSession(downstreamAgentId)
DownstreamSvc->>SessionCache: get(downstreamAgentId)
alt No Active Session
SessionCache-->>DownstreamSvc: null
DownstreamSvc->>DownstreamSvc: getOrCreateSession()
DownstreamSvc->>SessionCache: put(agentId, newSessionId)
DownstreamSvc-->>AgentExecCtrl: newSessionId
else Session Exists
SessionCache-->>DownstreamSvc: activeSessionId
alt Session ID Matches
DownstreamSvc-->>AgentExecCtrl: activeSessionId
else Session Conflict
DownstreamSvc-->>AgentExecCtrl: CONFLICT
AgentExecCtrl-->>Client: 409 Conflict
end
end
%% Call downstream Python service
AgentExecCtrl->>DownstreamSvc: runAgent(request)
DownstreamSvc->>PythonAI: POST /agents/{agentId}/run
Note over PythonAI,MCPServers: Python AI orchestrates tool calls
PythonAI->>MCPServers: Execute tools (Jira/GitHub/Webex/etc)
MCPServers-->>PythonAI: Tool results
PythonAI-->>DownstreamSvc: DownstreamAgentRunResponse
DownstreamSvc-->>AgentExecCtrl: response
%% Handle session cleanup
alt is_last_session = true OR error status
AgentExecCtrl->>DownstreamSvc: clearSession(agentId)
DownstreamSvc->>SessionCache: remove(agentId)
end
AgentExecCtrl-->>Client: 200 OK (DownstreamAgentRunResponse)
3. MCP Tool Discovery Flow (Startup)
sequenceDiagram
autonumber
participant SpringBoot as Spring Boot
participant MCPDiscovery as MCPDiscoveryService
participant MCPToolRegistry
participant JiraMCP as Jira MCP Server
participant ConfluenceMCP as Confluence MCP Server
participant GitHubMCP as GitHub MCP Server
participant WebexMCP as Webex MCP Server
Note over SpringBoot: Application Startup
SpringBoot->>MCPDiscovery: @PostConstruct discoverTools()
%% Jira Discovery (JSON-RPC)
MCPDiscovery->>JiraMCP: POST / (tools/list)
Note right of MCPDiscovery: JSON-RPC: {method: "tools/list"}
JiraMCP-->>MCPDiscovery: {tools: [...]}
MCPDiscovery->>MCPToolRegistry: registerTool(mcp_jira_*)
%% Confluence Discovery (JSON-RPC)
MCPDiscovery->>ConfluenceMCP: POST / (tools/list)
ConfluenceMCP-->>MCPDiscovery: {tools: [...]}
MCPDiscovery->>MCPToolRegistry: registerTool(mcp_confluence_*)
%% GitHub Discovery (JSON-RPC)
MCPDiscovery->>GitHubMCP: POST / (tools/list)
GitHubMCP-->>MCPDiscovery: {tools: [...]}
MCPDiscovery->>MCPToolRegistry: registerTool(mcp_github_*)
%% Webex Discovery (REST API)
MCPDiscovery->>WebexMCP: GET /mcp/tools
Note right of MCPDiscovery: REST API (different pattern)
WebexMCP-->>MCPDiscovery: [{name, description}, ...]
MCPDiscovery->>MCPToolRegistry: registerTool(mcp_webex_*)
MCPDiscovery-->>SpringBoot: Discovery complete
Note over SpringBoot: Total tools registered: N
4. LLM-Powered Tool Selection
sequenceDiagram
autonumber
participant MetaAgentSvc as MetaAgentService
participant LLMService
participant LLMProvider as LLM Provider (GPT/Claude)
participant MCPToolRegistry
MetaAgentSvc->>MCPToolRegistry: getAllTools()
MCPToolRegistry-->>MetaAgentSvc: List<MCPTool>
MetaAgentSvc->>LLMService: analyzeAgentDescription(name, desc, tools)
LLMService->>LLMService: buildAnalysisPrompt()
Note right of LLMService: Includes agent info + all available tools
LLMService->>LLMProvider: POST /chat/completions
Note right of LLMService: Model: gpt-4 / claude-3 / gemini
LLMProvider-->>LLMService: JSON Response
Note right of LLMProvider: {selectedTools, goal, executionMode, permissions}
LLMService->>LLMService: parseAnalysisResponse()
LLMService-->>MetaAgentSvc: LLMAnalysisResult
MetaAgentSvc->>MetaAgentSvc: Build AgentSpec from result
MetaAgentSvc-->>MetaAgentSvc: AgentSpec
MCP Tool Selection Strategies
The framework supports three different strategies for deciding which MCP tools to select when creating an agent:
| Strategy | Description | Best For |
|---|---|---|
| 1. Static Keyword Mapping | Tokenizes query and matches against predefined keyword mappings | Fast, deterministic results |
| 2. LLM-Based Selection | Uses AI (GPT-4/Claude) to semantically analyze and select tools | Complex, novel queries |
| 3. Cosine Similarity | Vector embeddings with cosine similarity scoring | Large catalogs, multi-language |
ββββββββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββββ¬βββββββββββββββββββββ
β β KEYWORD MAPPING β LLM SELECTION β COSINE SIMILARITY β
ββββββββββββββββββββΌβββββββββββββββββββΌβββββββββββββββββββΌβββββββββββββββββββββ€
β Latency β < 10ms β‘ β 500ms - 2s π’ β 50-200ms π β
β Cost per Query β $0 π° β $0.01-0.10 πΈ β $0.0001 π° β
β Accuracy β 70-80% β 90-95% β 85-92% β
β Semantic Aware β β No β β
Yes β β
Yes β
ββββββββββββββββββββ΄βββββββββββββββββββ΄βββββββββββββββββββ΄βββββββββββββββββββββ
For detailed documentation with diagrams, code examples, and implementation details, see:
MCP Tool Selection Strategies Documentation
Module Structure
agent-framework/
βββ build.gradle # Root build config
βββ settings.gradle # Multi-module settings
βββ docker-compose.yml # PostgreSQL container
βββ README.md # This file
β
βββ src/main/ # Main Application Module
β βββ java/com/agentframework/
β β βββ AgentFrameworkApplication.java
β β β
β β βββ controller/ # REST API Layer
β β β βββ AgentCrudController.java
β β β βββ AgentExecutionController.java
β β β βββ AgentLegacyController.java
β β β βββ AgentUtilityController.java
β β β βββ ToolController.java
β β β
β β βββ dto/ # Data Transfer Objects
β β β βββ CreateAgentRequest.java
β β β βββ AgentCreateResponse.java
β β β βββ AgentSpec.java
β β β βββ RunAgentRequest.java
β β β βββ DownstreamAgent*.java
β β β βββ ... (30+ DTOs)
β β β
β β βββ exception/ # Exception Handling
β β β βββ GlobalExceptionHandler.java
β β β
β β βββ facade/ # Orchestration Layer
β β β βββ AgentFacade.java
β β β βββ impl/
β β β βββ AgentFacadeImpl.java
β β β
β β βββ registry/ # Tool Registry
β β β βββ MCPTool.java
β β β βββ MCPToolRegistry.java
β β β
β β βββ service/ # Business Logic
β β βββ AgentCreationService.java
β β βββ AgentExecutorService.java
β β βββ ConfigDeciderService.java
β β βββ DownstreamAgentService.java
β β βββ LLMService.java
β β βββ MCPDataFetcherService.java
β β βββ MCPDiscoveryService.java
β β βββ MetaAgentService.java
β β
β βββ resources/
β βββ application.yaml # Main configuration
β βββ application.properties # DB connection
β βββ schema.sql # Database schema
β
βββ agent-common/ # Shared DTOs Module
β βββ src/main/java/.../common/dto/
β βββ AgentConfigDto.java
β βββ AgentDto.java
β
βββ agent-data/ # Data Access Module
βββ src/main/java/.../data/
βββ config/
β βββ DataModuleConfig.java
βββ entity/
β βββ Agent.java
β βββ AgentMcpServer.java
β βββ McpToolEntity.java
β βββ StringArrayConverter.java
βββ facade/
β βββ AgentDataFacade.java
β βββ impl/
β βββ AgentDataFacadeImpl.java
βββ repository/
βββ AgentRepository.java
βββ McpToolRepository.java
API Reference
Agent Management
| Method | Endpoint | Description |
|---|---|---|
POST | /api/agents | Create a new agent |
GET | /api/agents | List all agents |
GET | /api/agents/{id} | Get agent by ID |
GET | /api/agents/{id}/config | Get agent configuration |
DELETE | /api/agents/{id} | Delete an agent |
Agent Execution
| Method | Endpoint | Description |
|---|---|---|
POST | /api/agents/{id}/run | Run an agent with a query |
DELETE | /api/agents/{id}/session | Clear agent session |
Tools
| Method | Endpoint | Description |
|---|---|---|
GET | /api/tools | List all available MCP tools |
GET | /api/tools/categories | List tool categories |
Example Requests
Create Agent:
curl -X POST http://localhost:8080/api/agents \
-H "Content-Type: application/json" \
-d '{
"name": "Jira Issue Tracker",
"description": "Search and manage Jira issues",
"ownerId": "user-123",
"tenantId": "tenant-456"
}'
Run Agent:
curl -X POST http://localhost:8080/api/agents/{agentId}/run \
-H "Content-Type: application/json" \
-d '{
"query": "Find all open bugs assigned to me",
"userId": "user-123",
"maxIterations": 5,
"autoApprove": true
}'
Configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
LLM_ENABLED | Enable LLM for tool selection | false |
LLM_PROVIDER | LLM provider (cisco, openai, anthropic, gemini) | none |
LLM_API_KEY | API key for LLM provider | - |
LLM_MODEL | Model to use | Provider default |
MCP_DISCOVERY_ENABLED | Auto-discover tools at startup | false |
MCP_JIRA_URL | Jira MCP server URL | - |
JIRA_PAT_TOKEN | Jira Personal Access Token | - |
MCP_CONFLUENCE_URL | Confluence MCP server URL | - |
CONFLUENCE_PAT_TOKEN | Confluence PAT | - |
MCP_GITHUB_URL | GitHub MCP server URL | - |
GITHUB_PAT_TOKEN | GitHub PAT | - |
MCP_WEBEX_URL | Webex MCP server URL | - |
WEBEX_TOKEN | Webex access token | - |
DOWNSTREAM_AGENT_URL | Python AI service URL | http://localhost:8082 |
Database Configuration
# application.properties
spring.datasource.url=jdbc:postgresql://localhost:5432/agent_framework
spring.datasource.username=agent_user
spring.datasource.password=agent_pass
Quick Start
Prerequisites
- Java 21+
- Gradle
- Docker (for PostgreSQL)
1. Start PostgreSQL
docker compose up -d
2. Configure Environment
export LLM_ENABLED=true
export LLM_PROVIDER=openai
export LLM_API_KEY=your-api-key
export DOWNSTREAM_AGENT_URL=http://localhost:8082
3. Run the Application
./gradlew bootRun
4. Verify
curl http://localhost:8080/api/tools
Stop PostgreSQL
docker compose down
# To wipe data:
docker compose down -v
Technology Stack
| Component | Technology |
|---|---|
| Framework | Spring Boot 3.x |
| Language | Java 21 |
| Database | PostgreSQL 16 |
| ORM | Spring Data JPA / Hibernate |
| HTTP Client | Spring WebFlux (WebClient) |
| Build Tool | Gradle |
| Containerization | Docker |
| LLM Integration | OpenAI / Anthropic / Gemini / Cisco LLM Proxy |
License
Internal use only.
