KOI Agent Personality Network MCP server for AI agents

The KOI-MCP integration serves as a bridge between the Knowledge Organization Infrastructure (KOI) and the Model Context Protocol (MCP), allowing autonomous agents to share personality traits and expose capabilities as standardized tools that can be used by AI systems.

Installation

Prerequisites

Python 3.12 or higher
rid-lib (≥3.2.5)
koi-net (≥1.0.0b12)

Setting Up the Environment

# Clone the repository
git clone https://github.com/block-science/koi-mcp.git
cd koi-mcp

# Create and activate virtual environment
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package with development dependencies
uv pip install -e ".[dev]"

Running the Server

Quick Demo

The easiest way to get started is by running the included demo:

python scripts/demo.py

This launches an interactive console with detailed event logging and status displays.

Alternatively, use the main module for a simplified demo:

# Run demo (starts coordinator and two example agents)
python -m koi_mcp.main demo

After running the demo, you can access:

Coordinator Registry: http://localhost:9000/resources/list
Helpful Agent Tools: http://localhost:8101/tools/list
Creative Agent Tools: http://localhost:8102/tools/list

Running Components Separately

For more control, you can run each component individually:

# Run coordinator node
python -m koi_mcp.main coordinator

# Run agent nodes
python -m koi_mcp.main agent --config configs/agent1.json
python -m koi_mcp.main agent --config configs/agent2.json

Configuration

Coordinator Configuration

Create a JSON configuration file for the coordinator:

{
  "coordinator": {
    "name": "koi-mcp-coordinator",
    "base_url": "http://localhost:9000/koi-net",
    "mcp_registry_port": 9000
  }
}

Agent Configuration

Create a JSON configuration file for each agent:

{
  "agent": {
    "name": "helpful-agent",
    "version": "1.0",
    "base_url": "http://localhost:8100/koi-net",
    "mcp_port": 8101,
    "traits": {
      "mood": "helpful",
      "style": "concise",
      "interests": ["ai", "knowledge-graphs"],
      "calculate": {
        "description": "Performs simple calculations",
        "is_callable": true
      }
    }
  },
  "network": {
    "first_contact": "http://localhost:9000/koi-net"
  }
}

Using the API

Coordinator Registry Endpoints

GET /resources/list: View all registered agent resources
GET /resources/read/{resource_id}: Get details for a specific agent
GET /tools/list: See all available agent tools

Agent Server Endpoints

GET /resources/list: View this agent's personality as a resource
GET /resources/read/agent:{name}: Get this agent's personality details
GET /tools/list: See this agent's callable traits as tools
POST /tools/call/{trait_name}: Call a specific trait as a tool

Advanced Usage

Updating Agent Traits at Runtime

Agents can dynamically update their personality traits:

agent = KoiAgentNode(...)
agent.update_traits({
    "mood": "enthusiastic",
    "new_capability": {
        "description": "A new capability added at runtime",
        "is_callable": True
    }
})

Personality Model Structure

Agent personalities are built using a trait-based model:

# Example agent configuration
{
  "agent": {
    "name": "helpful-agent",
    "version": "1.0",
    "traits": {
      "mood": "helpful",
      "style": "concise",
      "interests": ["ai", "knowledge-graphs"],
      "calculate": {
        "description": "Performs simple calculations",
        "is_callable": true
      }
    }
  }
}

Traits can be:

Simple values (strings, numbers, booleans, lists)
Complex objects with metadata (description, type, is_callable)
Callable tools that can be invoked by LLM clients

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "koi-agent-personality-network" '{"command":"python","args":["-m","koi_mcp.main","coordinator"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "koi-agent-personality-network": {
            "command": "python",
            "args": [
                "-m",
                "koi_mcp.main",
                "coordinator"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "koi-agent-personality-network": {
            "command": "python",
            "args": [
                "-m",
                "koi_mcp.main",
                "coordinator"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect