> For the complete documentation index, see [llms.txt](https://docs.ovaledge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ovaledge.com/release8.1/mcp-server/deployment-options/local-mcp.md).

# 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

<table><thead><tr><th width="274.0001220703125">File</th><th>Description</th></tr></thead><tbody><tr><td>entrypoints/local.py </td><td>Initializes the local FastMCP lifespan, token exchange process, and stdio transport </td></tr><tr><td>server/app.py </td><td>Defines tools, resources, prompts, static documentation, and shared FastMCP application components </td></tr></tbody></table>

### Authentication and Token Lifecycle

<table><thead><tr><th width="268.666748046875">File</th><th>Description</th></tr></thead><tbody><tr><td>server/auth/token_exchange.py </td><td>Handles token exchange, token refresh, token expiration validation, and cache invalidation </td></tr><tr><td>server/auth/context.py </td><td>Maintains current_oe_jwt ContextVar and local JWT cache </td></tr><tr><td>server/client.py </td><td>Validates local token availability and retries requests after local 401 responses </td></tr></tbody></table>

### Configuration Management

<table><thead><tr><th width="274">File</th><th>Description</th></tr></thead><tbody><tr><td>server/config.py </td><td>Loads .env configuration values, including authentication mode, base URL, credentials, retry settings, and HTTP authentication scheme </td></tr></tbody></table>

## Install Local MCP on macOS and Linux&#x20;

### Configure Script Permissions&#x20;

* 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&#x20;

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

  ```
  ./scripts/setup_local_mcp.sh --dev
  ```

## Install Local MCP on Windows&#x20;

### 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&#x20;

* 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&#x20;

* Configure the mcp.json file as follows:

  ```json
  {
    "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"
        }
      }
    }
  }
  ```

{% hint style="info" %}

* If the .env file already contains the required values, any additional environment variables in the mcp.json configuration can be omitted.&#x20;
* Restart the MCP client after modifying the configuration.
  {% endhint %}

#### 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&#x20;
   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&#x20;
   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

<table><thead><tr><th width="274">Path</th><th>Description</th></tr></thead><tbody><tr><td>entrypoints/local.py </td><td>Local stdio entrypoint </td></tr><tr><td>server/app.py </td><td>MCP application assembly </td></tr><tr><td>server/auth/* </td><td>Token exchange and authentication context </td></tr><tr><td>server/client.py </td><td>Outbound OvalEdge HTTP client </td></tr><tr><td>server/tools/* </td><td>MCP tools </td></tr><tr><td>server/resources/* </td><td>MCP resources </td></tr><tr><td>server/prompts/workflows.py </td><td>Workflow prompt definitions </td></tr><tr><td>scripts/setup_local_mcp.sh </td><td>macOS and Linux setup script </td></tr><tr><td>scripts/setup_local_mcp.ps1 </td><td>Windows PowerShell setup script </td></tr></tbody></table>

***

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ovaledge.com/release8.1/mcp-server/deployment-options/local-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.