MCP Setup

Model Context Protocol (MCP) adds powerful extensibility to Kodezi CLI. It allows the AI to interact with databases, APIs, cloud services, custom tools, automation scripts, and real-time systems, directly through your terminal.

What is MCP?

MCP (Model Context Protocol) is a standardized way for AI systems to communicate with external tools.

Using MCP, Kodezi CLI can:

Access external data sources: Connect to databases, APIs, and file systems
Execute custom operations: Run domain specific commands and workflows
Integrate with third-party services: Extend with external tools and platforms
Add domain specific tools: Create specialized tools for your use cases

MCP turns Kodezi CLI from an AI assistant into a fully programmable AI environment.

MCP Connection Types

Kodezi CLI supports three MCP connection types:

stdio (Standard I/O)

Most common type. Spawns a process and communicates via standard input/output.

Best for:

Local MCP servers
Node/Python scripts
NPM packages
Tools installed globally
Database access utilities

Configuration Example:

{
  "mcp": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kodezi/mcp-database"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

HTTP

Communicates with MCP server via HTTP requests.

Best for:

Microservices
REST API wrappers
Internal company services
Authentication gateways

Configuration Examples:

{
  "mcp": {
    "api": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

SSE (Server-Sent Events)

Streams data from server using Server-Sent Events.

Best for:

Real time dashboards
Event driven systems
Continuous monitoring
Log streams

Configuration Example:

{
  "mcp": {
    "stream": {
      "type": "sse",
      "url": "http://localhost:3000/stream",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Configure MCP in Kodezi CLI

Add MCP servers to ~/.config/kodezi-cli/kodezi-cli.json:

{
  "mcp": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kodezi/mcp-database"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    },
    "api": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

MCP Configuration Options

For stdio servers

Field	Description
`type`	Must be `"stdio"`
`command`	Required executable (e.g., node, python, npx)
`args`	Arguments passed to the command
`env`	Environment variables (DB credentials, API keys)
`timeout`	Execution timeout in seconds
`disabled`	Disable tool without removing it

For http or sse servers

Field	Description
`type`	`"http"` or `"sse"`
`url`	Required MCP server URL
`headers`	Authentication or custom headers
`timeout`	Request timeout
`disabled`	Disable server

Install MCP Servers

You can install MCP servers in multiple ways.

Option A: Install NPM Based MCP Server

npm install -g @example/kodezi-mcp-server

Then configure:

{
  "mcp": {
    "example": {
      "type": "stdio",
      "command": "kodezi-mcp-server",
      "args": []
    }
  }
}

Option B: Install From Source

git clone https://github.com/example/mcp-server
cd mcp-server
npm install
npm link

Configure:

{
  "mcp": {
    "example": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server/index.js"]
    }
  }
}

Example Configurations

Database MCP

Connect to databases for querying and data operations:

{
  "mcp": {
    "database": {
      "type": "stdio",
      "command": "kodezi-mcp-database",
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "myapp",
        "DB_USER": "user",
        "DB_PASS": "password"
      }
    }
  }
}

HTTP API MCP

Connect to external HTTP APIs:

{
  "mcp": {
    "api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      },
      "timeout": 30
    }
  }
}

File Storage MCP

Connect to cloud storage services like S3:

{
  "mcp": {
    "storage": {
      "type": "stdio",
      "command": "kodezi-mcp-s3",
      "env": {
        "AWS_ACCESS_KEY_ID": "${AWS_ACCESS_KEY_ID}",
        "AWS_SECRET_ACCESS_KEY": "${AWS_SECRET_ACCESS_KEY}",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Environment Variables

MCP supports variable substitution:

${VAR} or $VAR: Environment variable
$(command): Command substitution

Example:

{
  "mcp": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kodezi/mcp-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}",
        "API_KEY": "$(cat ~/.api-key)"
      }
    }
  }
}

Using MCP Tools

Once configured, MCP tools are available automatically. The AI will use them when appropriate:

> "Query active users from the database"
# Uses database MCP tool

> "Call the payment API"
# Uses API MCP tool

Project Specific Configuration

Add to kodezi-cli.json in your project:

{
  "mcp": {
    "project-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kodezi/mcp-database"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/project_db"
      }
    }
  }
}

This overrides global configuration.

Troubleshooting

Security

Security Best Practices

When configuring MCP servers, follow these security practices:

Store Secrets Securely

Never hardcode secrets in configuration files. Always use environment variables.:

{
  "mcp": {
    "secure": {
      "type": "stdio",
      "command": "mcp-server",
      "env": {
        "API_KEY": "${API_KEY}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

Set environment variables in your shell:

export API_KEY="your-key"
export DB_PASSWORD="your-password"

Permissions

MCP tools respect the permission system. The user must approve MCP tool operations before they execute. This provides an additional security layer.

Audit MCP Servers

Only install MCP servers from trusted sources. Review the code if possible before installation.

Settings: All configuration options
Configuration: Configuration overview

MCP Setup

MCP Server Not Starting

Tool Not Available

Timeout Errors

On this page