Skip to main content
Glama

Vibe MCP Server

Enterprise-grade Model Context Protocol (MCP) server for the Vibe APIs, enabling seamless AI agent integration with production-ready architecture.

Features

  • Enterprise Architecture: Modular, scalable, and maintainable codebase

  • Production-Ready: Comprehensive error handling, logging, and monitoring

  • Async/Await: Full async implementation for high performance

  • Type Safety: Pydantic models for all request/response validation

  • Retry Logic: Automatic exponential backoff for transient failures

  • Observability: Structured JSON logging for debugging and monitoring

  • Connection Pooling: Efficient HTTP client with connection reuse

  • Token Management: Secure Bearer token authentication

Architecture

app/
├── config/              # Configuration management
│   └── settings.py      # Environment-based settings
├── core/                # Core infrastructure
│   ├── constants.py     # Centralized constants
│   ├── exceptions.py    # Application exception hierarchy
│   ├── http_client.py   # Reusable HTTP client with retries
│   ├── lifecycle.py     # Application startup/shutdown
│   └── logging.py       # Structured logging configuration
├── models/              # Pydantic request/response models
│   ├── activity.py
│   ├── bucket.py
│   ├── code.py
│   ├── project.py
│   └── repository.py
├── services/            # Business logic layer
│   └── vibe_api.py      # High-level Vibe API client
├── tools/               # MCP tool implementations
│   └── vibe_tools.py    # Tool wrappers for MCP
└── main.py              # MCP server entry point

Quick Start

Prerequisites

  • Python 3.12+

  • uv package manager

  • .env file with configuration

Installation

  1. Clone and navigate to the project:

    cd McpServer_Vibe
  2. Create and activate virtual environment:

    uv venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  3. Install dependencies:

    uv pip install -e ".[dev]"

Configuration

  1. Copy environment template:

    cp .env.example .env
  2. Update .env with your credentials:

    VIBE_BASE_URL=
    VIBE_ACCESS_TOKEN=
    LOG_LEVEL=INFO
    MCP_TRANSPORT=stdio

Running the Server

As Python Module

python -m app.main

Using uv

uv run app/main.py

Using Entry Point

vibe-mcp

Available Tools

1. get_project_list

Retrieve all projects from the Vibe system.

Parameters:

  • environment (optional): Environment name (default: "production")

Example:

{
  "environment": "production"
}

2. create_repo

Create a new repository in the Vibe system.

Parameters:

  • repo_id (required): Unique repository ID

  • project_id (required): Associated project ID

  • repo_name (required): Repository name

  • repo_description (optional): Repository description

  • functional_area (optional): Functional area

  • allow_ui_execution (optional): UI execution flag (0 or 1)

  • sync_status (optional): Sync status

  • comments (optional): Additional comments

  • version_id (optional): Version ID

3. create_bucket

Create a bucket for test execution organization.

Parameters:

  • bucket_id (required): Unique bucket ID

  • execution_order (required): Execution order

  • bucket_name (required): Bucket name

  • bucket_description (optional): Description

  • functional_area (optional): Functional area

  • bucket_type (optional): Bucket type

  • version_id (optional): Version ID

  • repo_id (optional): Repository ID

  • environment (optional): Environment name

4. get_activity

Retrieve activity details by bucket ID.

Parameters:

  • bucket_id (required): Bucket ID

  • version_id (required): Version ID

  • environment (optional): Environment name

5. get_code

Retrieve code/script by query ID.

Parameters:

  • query_id (required): Query/Code ID

  • version_id (required): Version ID

6. health_check

Verify Vibe API server health and accessibility.

Parameters: None

Integration with AI Clients

Claude Desktop

  1. Create/update Claude config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "vibe": {
      "command": "python",
      "args": ["-m", "app.main"],
      "env": {
        "VIBE_BASE_URL": "your_url_here",
        "VIBE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
  1. Restart Claude Desktop to load the MCP server.

Cursor

Similar configuration as Claude Desktop, update your Cursor MCP settings.

VS Code with MCP Extension

Install the MCP Client extension and add to your settings:

{
  "mcp.servers": {
    "vibe": {
      "command": "python",
      "args": ["-m", "app.main"],
      "env": {
        "VIBE_BASE_URL": "your_url_here",
        "VIBE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Environment Configuration

All configuration is managed through environment variables in .env file:

Variable

Default

Description

VIBE_BASE_URL

your_url_here

Vibe API base URL

VIBE_ACCESS_TOKEN

Required

Bearer token for authentication

LOG_LEVEL

INFO

Logging level (DEBUG, INFO, WARNING, ERROR)

VIBE_MAX_RETRIES

3

Max retry attempts for failed requests

VIBE_RETRY_BACKOFF_SECONDS

0.5

Initial backoff time (exponential)

MCP_TRANSPORT

stdio

MCP transport (stdio, sse)

MCP_HOST

0.0.0.0

MCP server host

MCP_PORT

9000

MCP server port

ENABLE_HEALTH_CHECK

true

Enable health check tool

ENABLE_METRICS

true

Enable metrics collection

Development

Running Tests

# Install dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest tests/ -v

# Run with coverage report
uv run pytest tests/ --cov=app --cov-report=html

# Run specific test
uv run pytest tests/test_vibe_server.py::TestHttpClient -v

See TESTING.md for comprehensive testing documentation.

Linting and Type Checking

# Lint with ruff
uv run ruff check app/

# Type checking with pyright
uv run pyright app/

Running in Development Mode

LOG_LEVEL=DEBUG uv run app/main.py

Error Handling

The server implements enterprise-grade error handling:

  • VibeAuthenticationError: Invalid or expired token (HTTP 401)

  • VibeNotFoundError: Resource not found (HTTP 404)

  • VibeValidationError: Request validation failure

  • VibeTimeoutError: Request timeout

  • VibeConnectionError: Network connectivity issues

All errors are automatically logged with structured context for debugging.

Retry Mechanism

Failed requests are automatically retried with exponential backoff:

  • Max retries: Configurable (default: 3)

  • Backoff multiplier: Exponential (1, 2, 4, 8 seconds)

  • Retryable errors: Timeouts, connection errors, server errors

  • Non-retryable: Authentication errors (401), validation errors

Logging

Structured JSON logging provides detailed observability:

{
  "event": "HTTP request successful",
  "timestamp": "2024-05-19T10:30:45.123456Z",
  "level": "info",
  "logger": "http_client",
  "method": "GET",
  "endpoint": "/api/Project/GetProjectList",
  "status_code": 200
}

Enable debug logging for detailed request/response traces:

LOG_LEVEL=DEBUG python -m app.main

Performance Considerations

  • Connection Pooling: HTTP client maintains persistent connections (10 max)

  • Timeout Configuration: 30-second request timeout, 10-second connect timeout

  • Async Processing: All operations are async for concurrent execution

  • Memory Efficiency: Structured streaming responses for large datasets

Security

  • Token Handling: Bearer tokens are stored securely in SecretStr and never logged

  • HTTPS: All connections use HTTPS by default

  • Input Validation: All inputs validated against Pydantic models

  • Output Sanitization: Responses are validated before returning to clients

Troubleshooting

Connection Issues

  1. Verify network connectivity:

    curl -H "Authorization: Bearer $VIBE_ACCESS_TOKEN" \
      "your_url_here"
  2. Check VPN/Proxy if required for your network

  3. Enable debug logging:

    LOG_LEVEL=DEBUG python -m app.main

Authentication Errors

  1. Verify token is valid and not expired

  2. Check token format: Should be Bearer <token>

  3. Ensure .env file is loaded:

    cat .env | grep VIBE_ACCESS_TOKEN

Timeout Issues

  1. Increase timeout in production (edit http_client.py)

  2. Check network latency to Vibe API

  3. Reduce concurrent requests if hitting rate limits

Contributing

For contributing to this project:

  1. Follow PEP 8 style guide

  2. Add type annotations to all functions

  3. Write tests for new features

  4. Update documentation

  5. Run linting and type checks before submitting

License

This project is proprietary and maintained by the engineering team.

Support

For issues or questions:

  1. Check the troubleshooting section

  2. Review structured logs for error context

  3. Contact the engineering team with:

    • Error message and stack trace

    • Relevant log output

    • Steps to reproduce the issue

Available Tools

6 tools
create_bucketC

Create a new bucket in the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault
bucket_idYes
execution_orderYes
bucket_nameYes
bucket_descriptionNo
functional_areaNo
bucket_typeNo
version_idNo
repo_idNo
environmentNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description indicates a write operation but lacks details on side effects, permissions, or response behavior; no annotations to supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise, but could include more substance without losing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters (3 required) and no parameter descriptions, the description is insufficient for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and description does not explain any parameter meanings, leaving the agent to infer from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description 'Create a new bucket in the Vibe system' clearly states the action (create) and resource (bucket), distinguishing it from sibling tools like create_repo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites or context for invocation provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_repoC

Create a new repository in the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault
repo_idYes
project_idYes
repo_nameYes
repo_descriptionNo
functional_areaNo
allow_ui_executionNo
sync_statusNo
commentsNo
version_idNo
environmentNoDevelopment

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral details. It only says 'creates a new repository', but doesn't mention idempotency, error handling, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise, but lacks necessary detail. It is not overly verbose but fails to add value beyond the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, no annotations, output schema exists but not described), the description is severely incomplete. It does not help the agent understand usage or expected behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no explanation of the 10 parameters, including required fields like repo_id and project_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a new repository in the Vibe system', which is a specific verb+resource. It distinguishes from sibling tools like create_bucket, get_activity, etc., which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, or any prerequisites or context. The description is generic.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_activityC

Get activity information from the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault
bucket_idYes
version_idYes
environmentNoDevelopment

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does not mention side effects, authentication requirements, or any constraints. The presence of an output schema does not compensate for the lack of behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and to the point. However, it is so short that it sacrifices completeness for brevity, which prevents a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of three parameters and the presence of an output schema, the description is insufficient. It lacks parameter explanations, usage context, and behavioral notes, making it incomplete for reliable tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage for parameters, and the tool description adds no meaning to any parameter. The description does not explain what 'bucket_id', 'version_id', or 'environment' represent, leaving the agent without necessary context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and resource 'activity information', and distinguishes this tool from siblings like 'get_code' and 'get_project_list'. However, it lacks specificity about what kind of activity, so it is not a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description is purely declarative with no context about appropriate scenarios or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_codeC

Get code information from the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault
query_idYes
version_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It only states the action (get) but omits details like idempotency, auth needs, or side effects. The simplicity of a get operation partially mitigates, but the burden is unmet.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no unnecessary words. Front-loaded with the action. However, it could be slightly expanded without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While output schema exists (so return values are covered), the description is too vague for a tool with two required params. It doesn't explain what 'code information' entails, leaving ambiguity. Minimal completeness for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has two required string parameters (query_id, version_id) with 0% description coverage. The description adds no meaning to these parameters—does not explain what each ID represents or how they relate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get code information from the Vibe system' uses a verb+resource pattern that clearly indicates retrieving code data. It distinguishes from sibling tools like create_bucket or get_activity, but is somewhat generic—could specify whether it's for a query or version.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. The description lacks context on prerequisites, typical use cases, or when other tools would be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_listC

Retrieve all projects from the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault
environmentNoDevelopment

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fails to disclose critical behavioral traits like pagination, authentication requirements, or whether the operation is safe. It only states 'retrieve,' implying read-only, but no depth is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, brief sentence that clearly states its purpose. It is front-loaded and efficient, though it could benefit from slight expansion without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description lacks context about what the output contains, how many projects are returned, or the effect of the 'environment' parameter. It feels incomplete for a list endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 1 parameter ('environment') with 0% description coverage. The description does not mention this parameter nor clarify its purpose or effect, adding no value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Retrieve all projects from the Vibe system,' specifying a clear verb ('retrieve') and resource ('projects from Vibe system'). This distinguishes the tool from siblings like 'create_bucket' or 'get_code'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as when to use 'get_project_list' vs 'get_activity' or 'get_code'. No criteria for selection are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

health_checkA

Check the health and connectivity of the Vibe system

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only says 'check health and connectivity' without disclosing whether it is read-only, if it requires authentication, or any side effects. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, concise sentence that conveys the purpose without any extraneous words. Front-loaded and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an output schema exists, the description is reasonably complete. It could mention that this is a lightweight readiness check or typical use case, but it is sufficient for a health check tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is 100%. The description adds no parameter-specific meaning, but with 0 parameters the baseline is 4. No further information needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Check' and the resource 'health and connectivity of the Vibe system', and distinguishes from sibling tools which deal with specific entities like buckets, repos, or activities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking system health, but does not explicitly state when to use it versus alternatives or provide any exclusions. For a simple health check, this is adequate but lacks guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedcreate_bucket
    • First observedcreate_repo
    • First observedget_activity
    • First observedget_code
    • First observedget_project_list
    • First observedhealth_check

TDQS

B3.2/5.0
Disambiguation5/5

Each tool targets a distinct resource or action: bucket creation, repo creation, activity retrieval, code retrieval, project listing, and health check. No overlap in purpose.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (e.g., create_bucket, get_activity), but health_check is noun_verb, creating a minor inconsistency.

Tool Count5/5

With 6 tools, the set feels well-scoped for a system managing buckets, repos, projects, and health. Not too few or too many.

Completeness2/5

Significant gaps exist: there are create operations for buckets and repos but no corresponding list, get, update, or delete operations for these resources. The get operations only cover activity, code, and a project list.

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Coding-Professional/McpServer_Vibe'

If you have feedback or need assistance with the MCP directory API, please join our Discord server