Полное руководство: подключение Cursor к пользовательскому MCP серверу

Проблема, с которой вы столкнулись, возникает из‑за того, что команда uv run mcp dev использует собственный прокси‑сервер, который переопределяет вашу указанную конфигурацию порта. При запуске серверов MCP через этот CLI‑инструмент автоматически создаётся прокси на портах 6274 и 6277, поэтому настройка port=5000 игнорируется. Чтобы корректно подключить Cursor к вашему пользовательскому серверу MCP, необходимо либо запускать сервер напрямую через uvicorn, либо правильно настроить прокси.

Содержание

• Понимание поведения uv run mcp dev
• Правильная конфигурация сервера MCP для Cursor
• Альтернативные подходы к запуску сервера
• Проверочный чек‑лист конфигурации
• Шаги тестирования и проверки

Понимание поведения uv run mcp dev

Когда вы используете команду uv run mcp dev, фактически не запускается ваш Python‑сервер напрямую. Вместо этого запускается инспектор MCP и прокси, который обрабатывает перевод протокола MCP. Поэтому вы видите прокси‑сервер, слушающий localhost:6277, и инспектор на localhost:6274.

Прокси MCP выступает в роли посредника, который:

• Переводит между различными транспортными протоколами MCP
• Обрабатывает токены аутентификации
• Предоставляет возможности отладки через UI инспектора

Однако такой подход иногда вызывает проблемы с подключением клиентов, таких как Cursor, поскольку добавляет дополнительный уровень сложности в цепочку соединения.

Согласно документации Smithery, при работе с серверами MCP часто необходимо отдельно учитывать как приложение‑сервер, так и конфигурацию прокси.

Правильная конфигурация сервера MCP для Cursor

Чтобы подключить Cursor напрямую к вашему серверу MCP, минуя прокси, у вас есть несколько вариантов:

Вариант 1: Запуск сервера напрямую через uvicorn

Измените ваш код сервера, чтобы он запускался напрямую с uvicorn:

from starlette.applications import Starlette
from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("sse")

@mcp.tool()
def get_current_time() -> str:
    from datetime import datetime
    now = datetime.now()
    return f"Time: {now.strftime('%Y-%m-%d %H:%M:%S')}"

app = Starlette(
    routes=[
        Mount('/', app=mcp.sse_app()),
    ]
)

if __name__ == "__main__":
    import uvicorn
    # Используем переменные окружения для гибкости
    import os
    host = os.getenv("HOST", "0.0.0.0")
    port = int(os.getenv("PORT", "5000"))
    
    print(f"Starting MCP server on {host}:{port}")
    uvicorn.run(app, host=host, port=port, log_level="info")

Затем запустите его напрямую:

uv run uvicorn your_file:app --host 0.0.0.0 --port 5000 --reload

Вариант 2: Использование CLI FastMCP

Если вы предпочитаете использовать CLI FastMCP, установите его и запустите:

fastmcp run your_server_file.py --port 5000

Этот подход, как описано в документации FastMCP, автоматически обнаруживает ваш экземпляр FastMCP и запускает его с указанными параметрами.

Вариант 3: Настройка Cursor для прямого подключения

Если вы хотите продолжать использовать инспектор для отладки, но подключать Cursor напрямую, настройте ваш mcp.json следующим образом:

{
  "mcpServers": {
    "hello": {
      "url": "http://localhost:5000",
      "transport": "sse"
    }
  }
}

Альтернативные подходы к запуску сервера

Использование uv run с прямой командой uvicorn

Как показано в статье AbdulKabir на Medium, вы можете запустить uvicorn напрямую через uv:

uv run uvicorn main:app --reload --port 5000

Где:

• main — имя вашего Python‑файла
• app — переменная, экспортируемая как приложение
• --reload — включает авто‑перезапуск при изменениях кода
• --port 5000 — задаёт порт

Использование uvicorn.Config для более тонкой настройки

Для более гибкой конфигурации используйте uvicorn.Config, как показано в официальной документации uvicorn:

import asyncio
import uvicorn

async def main():
    config = uvicorn.Config("your_module:app", port=5000, log_level="info")
    server = uvicorn.Server(config)
    await server.serve()

if __name__ == "__main__":
    asyncio.run(main())

Конфигурация через переменные окружения

Создайте гибкую конфигурацию, используя переменные окружения, как показано в реализации UselessAI:

import uvicorn
import os

HOST = os.getenv("HOST", "0.0.0.0")
PORT = int(os.getenv("PORT", "5000"))

def run():
    """Запуск FastAPI‑сервера с uvicorn"""
    uvicorn.run(app, host=HOST, port=PORT, log_level="info")

if __name__ == "__main__":
    run()

Проверочный чек‑лист конфигурации

Если Cursor всё ещё не может подключиться после внедрения вышеуказанных решений, проверьте следующие распространённые проблемы:

Сетевые и брандмауэрные проблемы

• Убедитесь, что порт 5000 не блокируется брандмауэром
• Проверьте, доступен ли сервер из сети Cursor
• Укажите полный адрес хоста (например, http://127.0.0.1:5000), если требуется

Несоответствие транспортного протокола

• Cursor ожидает транспорт SSE (Server‑Sent Events) для серверов MCP
• Убедитесь, что ваш FastMCP инициализирован с транспортом "sse"
• Проверьте, соответствует ли формат URL ожидаемому протоколу

Проблемы аутентификации

• Если используется прокси, убедитесь, что токен аутентификации корректно включён
• Для прямых подключений уберите требования к аутентификации
• Проверьте, не блокируют ли CORS заголовки кросс‑доменные запросы

Проблемы запуска сервера

• Подтвердите, что сервер действительно запущен и отвечает
• Проверьте логи сервера на наличие ошибок запуска
• Убедитесь, что переменная app корректно экспортирована

Шаги тестирования и проверки

Шаг 1: Тестирование сервера локально

Перед подключением Cursor протестируйте ваш сервер локально:

curl -N http://localhost:5000/

Вы должны увидеть ответ, подтверждающий, что сервер работает.

Шаг 2: Использование инспектора MCP для отладки

Даже при прямом запуске вы можете использовать инспектор MCP:

uv run mcp inspect http://localhost:5000

Шаг 3: Проверка доступности инструментов

Проверьте, правильно ли выставлены ваши инструменты, просмотрев SSE‑эндпоинт сервера:

# Добавьте этот тестовый эндпоинт в ваш сервер
@app.route("/tools")
def list_tools():
    return {"tools": [tool.name for tool in mcp.tools]}

Шаг 4: Проверка логов Cursor

Включите подробный лог в Cursor, чтобы увидеть детальные попытки подключения и ошибки.

Шаг 5: Тестирование с альтернативным клиентом

Попробуйте подключиться к вашему серверу MCP с помощью других совместимых клиентов, чтобы изолировать проблему.

Источники

1. Smithery Documentation - Build Python MCP Server with FastMCP
2. FastMCP Documentation - Running Your Server
3. AbdulKabir’s Medium Article - Mastering MCP Servers: From Import to Running with Uvicorn
4. UselessAI Article - Implementing MCP(FastMCP) in a FastAPI Application
5. Uvicorn Official Documentation
6. Stack Overflow - Cannot connect Cursor to my remote MCP server
7. HuggingFace Blog - How to Use FastAPI MCP Server: A Complete Guide

Заключение

Ключевой вывод: uv run mcp dev использует собственную инфраструктуру прокси, которая переопределяет вашу конфигурацию порта. Чтобы исправить проблему подключения с Cursor:

1. Запускайте ваш сервер напрямую с помощью uv run uvicorn your_file:app --port 5000 вместо uv run mcp dev.
2. Настройте mcp.json Cursor так, чтобы он указывал напрямую на URL вашего сервера (http://localhost:5000).
3. Используйте переменные окружения для гибкой настройки хоста и порта.
4. Проверьте соединение локально перед попыткой подключения Cursor.
5. Проверьте транспортные протоколы, чтобы убедиться, что SSE правильно настроен.

Самый надёжный подход — запускать ваш MCP‑сервер напрямую через uvicorn и конфигурировать Cursor для подключения к конкретному эндпоинту, полностью обходя прокси. Это даст полный контроль над настройкой порта и устранит проблемы, связанные с прокси.