home / mcp / pure agentic mcp server

Pure Agentic MCP Server

A pure agentic MCP server with dynamic tool registration and web UI for interactive tool usage.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "adamsalah13-mcp_server_full": {
      "url": "http://localhost:8000",
      "headers": {
        "OLLAMA_MODEL": "llama3.2",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

You run a Pure Agentic MCP Server that exposes capabilities as MCP tools through specialized agents. It supports the MCP protocol for Claude Desktop and HTTP endpoints for a web interface, while tools register dynamically at startup and operate with graceful degradation if any agent fails.

How to use

Start by running the local MCP server that talks to Claude Desktop and the HTTP host for the web UI. You will be able to invoke tools from Claude Desktop via MCP JSON-RPC and from the web UI or REST API.

How to install

Prerequisites - Python 3.11+ - Virtual environment support - Access to a shell or terminal

Installation steps 1. Clone the project repository 2. Navigate into the project folder 3. Create and activate a virtual environment 4. Install dependencies from the requirements file

Configuration

Set environment variables in a file named .env to configure agents. These variables are optional for some agents but enable key capabilities when provided.

OpenAI Agent (optional) OPENAI_API_KEY=your_openai_api_key_here

Ollama Agent (optional, uses a local server) OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_MODEL=llama3.2

File Agent (enabled by default, no config needed)

Running the server

For Claude Desktop (MCP Protocol) start the MCP server in stdio mode using Python

python run_mcp_server.py

For the HTTP web interface start the HTTP host and then the Streamlit UI

# Terminal 1: Start HTTP host for tools
python simple_mcp_host.py

# Terminal 2: Start Streamlit UI
streamlit run streamlit_app.py

Access the web interface at http://localhost:8501 and the HTTP API at http://localhost:8000

Testing your setup

Run quick checks to verify agent registration, tool availability, and overall server health.

python test_quick.py
python test_both.py
python validate_server.py

Security and maintenance

Keep API keys secure in the environment and monitor agent health. Agents degrade gracefully if individual components fail.

Notes on usage with Claude Desktop and HTTP UI

Claude Desktop commands map to tools exposed by agents. Use natural language prompts like “Read the contents of a file” or “Analyze this text with OpenAI” to trigger the corresponding tools.

Troubleshooting

If you encounter issues, verify agent keys and service availability, ensure the HTTP host is up before launching the Streamlit UI, and check that the correct start command is used for the MCP server.

Development notes

This server dynamically registers tools at startup. You can add new agents by implementing the base interface and registering them in the server configuration.

Available tools

openai_chat

Chat completion with OpenAI models via the OpenAI agent

openai_analysis

Text analysis and insights using OpenAI capabilities

ollama_chat

Chat with local Ollama models via the Ollama agent

ollama_generate

Text generation using Ollama models via the Ollama agent

file_read

Read the contents of a file from the filesystem

file_write

Write content to a file on the filesystem

file_list

List contents of a directory on the filesystem