MCP Server Integration

The Kumiho Python SDK includes a built-in Model Context Protocol (MCP) server that enables AI assistants like GitHub Copilot, Claude, and other MCP-compatible clients to interact with Kumiho Cloud directly.

What is MCP?

The Model Context Protocol is an open standard that allows AI assistants to connect to external data sources and tools. By exposing Kumiho’s functionality through MCP, AI assistants can:

Query and navigate your asset graphs
Analyze dependencies and impact of changes
Search for items across projects
Track AI lineage and provenance
Create, update, and manage revisions and artifacts
Build and manage bundles

Installation

Install the Kumiho SDK with MCP support:

pip install kumiho[mcp]

Or if you already have kumiho installed:

pip install mcp httpx

Authentication

Before running the MCP server, authenticate with Kumiho Cloud:

kumiho-auth login

This caches your credentials which the MCP server will use automatically.

Running the MCP Server

Standalone Mode

Run the MCP server directly:

kumiho-mcp

Or using Python module:

python -m kumiho.mcp_server

VS Code / GitHub Copilot Integration

Add the following to your VS Code settings.json:

{
    "mcp": {
        "servers": {
            "kumiho": {
                "command": "kumiho-mcp",
                "args": []
            }
        }
    }
}

Alternatively, if using a virtual environment:

{
    "mcp": {
        "servers": {
            "kumiho": {
                "command": "python",
                "args": ["-m", "kumiho.mcp_server"],
                "env": {
                    "PATH": "/path/to/your/venv/bin:${env:PATH}"
                }
            }
        }
    }
}

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "kumiho": {
            "command": "kumiho-mcp"
        }
    }
}

Available Tools

The MCP server exposes 39 tools organized by category:

Read Operations (14 tools)

Tool	Description
`kumiho_list_projects`	List all accessible projects
`kumiho_get_project`	Get project details by name
`kumiho_get_spaces`	Get spaces within a project
`kumiho_get_space`	Get a space by path
`kumiho_get_item`	Get an item by kref URI
`kumiho_search_items`	Search items with filters
`kumiho_get_item_revisions`	Get all revisions for an item
`kumiho_get_revision`	Get a revision by kref
`kumiho_get_revision_by_tag`	Get revision by tag (latest, published, etc.)
`kumiho_get_artifacts`	Get all artifacts for a revision
`kumiho_get_artifact`	Get a single artifact by kref
`kumiho_get_bundle`	Get a bundle by kref
`kumiho_resolve_kref`	Resolve kref to file location
`kumiho_get_artifacts_by_location`	Reverse lookup artifacts by file path

Graph Traversal (5 tools)

Tool	Description
`kumiho_get_dependencies`	Get what a revision depends on
`kumiho_get_dependents`	Get what depends on a revision
`kumiho_analyze_impact`	Analyze downstream impact of changes
`kumiho_find_path`	Find shortest path between revisions
`kumiho_get_edges`	Get edges (relationships) for a revision

Create Operations (8 tools)

Tool	Description
`kumiho_create_project`	Create a new project
`kumiho_create_space`	Create a space within a project
`kumiho_create_item`	Create an item within a space
`kumiho_create_revision`	Create a new revision for an item
`kumiho_create_artifact`	Create an artifact for a revision
`kumiho_create_bundle`	Create a bundle to group items
`kumiho_create_edge`	Create relationship between revisions
`kumiho_tag_revision`	Apply a tag to a revision

Delete Operations (6 tools)

Tool	Description
`kumiho_delete_project`	Delete a project
`kumiho_delete_space`	Delete a space
`kumiho_delete_item`	Delete an item
`kumiho_delete_revision`	Delete a revision
`kumiho_delete_artifact`	Delete an artifact
`kumiho_delete_edge`	Delete a relationship

Update Operations (6 tools)

Tool	Description
`kumiho_untag_revision`	Remove a tag from a revision
`kumiho_set_metadata`	Set metadata on item or revision
`kumiho_deprecate_item`	Mark an item as deprecated
`kumiho_add_bundle_member`	Add an item to a bundle
`kumiho_remove_bundle_member`	Remove an item from a bundle
`kumiho_get_bundle_members`	List all items in a bundle

Example Conversations

Once configured, you can ask your AI assistant questions like:

Exploring Assets

“List all projects I have access to”

“What items are in the ‘characters’ space of project ‘film-2024’?”

“Show me all revisions for kref://film-2024/characters/hero.model”

Dependency Analysis

“What does the hero model depend on?”

“If I change this texture, what assets will be affected?”

“Find the path between the hero rig and the final render”

Asset Management

“Create a new revision for kref://film-2024/props/sword.model with metadata artist=’john’”

“Tag revision kref://film-2024/characters/hero.model?r=5 as ‘approved’”

“Add the hero model to the ‘main-characters’ bundle”

AI Lineage Tracking

“What training data was used to generate this AI asset?”

“Show me all assets derived from this base model”

Kref URI Format

Tools use Kref URIs to reference Kumiho objects:

kref://project/space/item.kind           # Item
kref://project/space/item.kind?r=1       # Revision (r=revision number)
kref://project/space/item.kind?r=1&a=mesh  # Artifact (a=artifact name)

Examples:

kref://film-2024/characters/hero.model - Hero model item
kref://film-2024/characters/hero.model?r=3 - Revision 3
kref://film-2024/characters/hero.model?r=3&a=mesh.fbx - Mesh artifact

Edge Types

When creating or querying edges, use these relationship types:

Edge Type	Description
`DEPENDS_ON`	Asset depends on another asset
`DERIVED_FROM`	Asset was derived from another
`REFERENCED`	Asset references another
`CONTAINS`	Asset contains another
`CREATED_FROM`	AI asset created from training data
`BELONGS_TO`	Asset belongs to a bundle

Environment Variables

Variable	Description	Default
`KUMIHO_MCP_LOG_LEVEL`	Log level (DEBUG, INFO, WARNING, ERROR)	INFO

MCP Resources and Prompts

The server also exposes:

Resources

Projects are exposed as MCP resources with URI format kumiho://project/{name}.

Prompts

Prompt	Description
`analyze_asset`	Guided workflow to analyze an asset’s dependencies and impact
`find_assets`	Guided workflow to search for assets by kind and project

Troubleshooting

Server won’t start

Ensure MCP dependencies are installed:
```
pip install kumiho[mcp]
```
Check authentication:
```
kumiho-auth status
```
Enable debug logging:
```
KUMIHO_MCP_LOG_LEVEL=DEBUG kumiho-mcp
```

Tools not appearing in AI assistant

Verify the MCP configuration in your settings
Restart your AI assistant/editor
Check the MCP server logs for connection errors

Authentication errors

Refresh your credentials:

kumiho-auth refresh

Or re-authenticate:

kumiho-auth login

API Reference

For detailed API documentation of the MCP server module, see the MCP Server API Reference.