Local MCP

The Local MCP (Model Context Protocol) deployment enables the OvalEdge MCP server to run as a local stdio subprocess using AUTH_MODE=local. In this mode, MCP clients such as Cursor and Claude Desktop communicate with the server through JSON-RPC over standard input and output streams.

The local deployment uses machine credentials to generate and manage OvalEdge JWT tokens for authenticated API communication. The deployment also supports automatic token refresh, retry handling, and centralized configuration management.

This document describes the installation, configuration, runtime architecture, execution methods, troubleshooting procedures, and security recommendations for Local MCP deployment.

Prerequisites

Ensure the following prerequisites are available before starting the installation:

• Python 3.12 or later

• Poetry package manager

• Access to an OvalEdge environment

• Valid OvalEdge machine credentials:

  • OVALEDGE_USER_TOKEN

  • OVALEDGE_USER_SECRET

• Access to the following API endpoint:

  • /api/user/token/generate

• macOS, Linux, or Windows operating system

• Git repository containing the OvalEdge MCP source code

Local MCP Runtime Architecture

Local MCP mode uses machine credentials to obtain an OvalEdge JWT and execute authenticated API requests.

The runtime workflow is as follows:

1. The MCP client starts the stdio process using poetry run oe-mcp-local.

2. entrypoints/local.py initializes FastMCP with local_lifespan.

3. The lifespan process calls get_or_refresh_local_token().

4. OvalEdge sends a JWT response through the POST /api/user/token/generate API.

5. The JWT is cached in memory and stored in ContextVar.

6. Tools use OvalEdgeClient for outbound API communication.

7. The application validates token freshness before each request.

8. The application refreshes the token automatically when required.

9. The client invalidates the cache and retries the request once upon receiving a local 401 response.

Local MCP Components

Entrypoint and Application Composition

File	Description
entrypoints/local.py	Initializes the local FastMCP lifespan, token exchange process, and stdio transport
server/app.py	Defines tools, resources, prompts, static documentation, and shared FastMCP application components

Authentication and Token Lifecycle

File	Description
server/auth/token_exchange.py	Handles token exchange, token refresh, token expiration validation, and cache invalidation
server/auth/context.py	Maintains current_oe_jwt ContextVar and local JWT cache
server/client.py	Validates local token availability and retries requests after local 401 responses

Configuration Management

File	Description
server/config.py	Loads .env configuration values, including authentication mode, base URL, credentials, retry settings, and HTTP authentication scheme

Install Local MCP on macOS and Linux

Configure Script Permissions

• Run the following command to provide execute permission for the setup script:

  chmod +x scripts/setup_local_mcp.sh

Run the Installation Script

• Run the following command:

  ./scripts/setup_local_mcp.sh

Installation Actions

The setup script performs the following actions:

1. Verifies the operating system and Python 3.12 or later.

2. Installs Poetry if it is not available.

3. Executes poetry install.

4. Creates the .env file from .env.example if the file does not exist.

5. Performs a smoke import validation for entrypoints.local.

6. Displays an mcp.json configuration snippet.

Run Developer Mode Installation

• Run the following command to install development dependencies and validation utilities:

  ./scripts/setup_local_mcp.sh --dev

Install Local MCP on Windows

Run the PowerShell Installation Script

• Run the following command:

  powershell -ExecutionPolicy Bypass -File .\scripts\setup_local_mcp.ps1

Run Developer Mode Installation

• Run the following command:

  powershell -ExecutionPolicy Bypass -File .\scripts\setup_local_mcp.ps1 -Dev

Configure Environment Variable

• Configure the following variables in the .env file or through the MCP client environment configuration.

  AUTH_MODE=local
  OVALEDGE_BASE_URL=http://<host>:<port>/ovaledge
  OVALEDGE_USER_TOKEN=<token>
  OVALEDGE_USER_SECRET=<secret>
  OVALEDGE_HTTP_AUTH_SCHEME=jwt

Optional Environment Variables

OVALEDGE_TIMEOUT_SECONDS=
OVALEDGE_MAX_RETRIES=
OVALEDGE_RETRY_BACKOFF_SECONDS=
OVALEDGE_LOG_HTTP_REQUESTS=

Configure MCP Client

• Configure the mcp.json file as follows:

  {
    "mcpServers": {
      "ovaledge-local": {
        "command": "poetry",
        "args": [
          "-C",
          "/absolute/path/to/oe_mcp",
          "run",
          "oe-mcp-local"
        ],
        "env": {
          "OVALEDGE_BASE_URL": "http://127.0.0.1:8080/ovaledge",
          "OVALEDGE_USER_TOKEN": "user-token",
          "OVALEDGE_USER_SECRET": "user-secret",
          "OVALEDGE_HTTP_AUTH_SCHEME": "jwt",
          "AUTH_MODE": "local"
        }
      }
    }
  }

• If the .env file already contains the required values, any additional environment variables in the mcp.json configuration can be omitted.

• Restart the MCP client after modifying the configuration.

Run Local MCP Manually

• Run the following command to start Local MCP manually:

  poetry -C /absolute/path/to/oe_mcp run oe-mcp-local

Troubleshooting

1. TokenExchangeError with HTTP 200 and Empty Response

   1. Possible causes:

      1. Incorrect base URL

      2. Login page intercepting API requests

   2. Resolution steps:

      1. Verify the configured base URL.

      2. Confirm API routes support the following authorization format:

         Authorization: <scheme> <jwt>

2. MCP Client Does Not Start the Server

   1. Possible causes:

      1. Poetry is unavailable in the system path

      2. Invalid repository path

      3. Incomplete dependency installation

      4. Missing AUTH_MODE=local configuration

   2. Resolution steps:

      1. Verify Poetry installation and system path configuration.

      2. Verify the absolute repository path used with -C.

      3. Run poetry install.

      4. Verify the AUTH_MODE configuration.

Security Recommendations

Follow the security recommendations below during Local MCP deployment:

• Do not commit OVALEDGE_USER_TOKEN or OVALEDGE_USER_SECRET values to source control repositories.

• Rotate credentials immediately if exposure occurs.

• Use least-privilege OvalEdge service accounts for authentication.

Local MCP Directory Structure

Path	Description
entrypoints/local.py	Local stdio entrypoint
server/app.py	MCP application assembly
server/auth/*	Token exchange and authentication context
server/client.py	Outbound OvalEdge HTTP client
server/tools/*	MCP tools
server/resources/*	MCP resources
server/prompts/workflows.py	Workflow prompt definitions
scripts/setup_local_mcp.sh	macOS and Linux setup script
scripts/setup_local_mcp.ps1	Windows PowerShell setup script

---

Copyright © 2026, OvalEdge LLC, Peachtree Corners, GA, USA.