Why mcp-jpa?

Modules

Architecture

flowchart LR
    subgraph client["AI client"]
        Cursor["Cursor / MCP host"]
    end

    subgraph app["Spring Boot app"]
        EP["/mcp\nStreamable HTTP"]
        MCP["McpSyncServer"]
        Tools["JpaSchemaTools"]
        EMF["EntityManagerFactory"]
        EP --> MCP --> Tools --> EMF
    end

    subgraph db["Database"]
        PG[("PostgreSQL / …")]
    end

    Cursor -->|"VPN / internal network"| EP
    EMF --> PG

Transports

MCP tools

Example: describe_entity

{
  "entityName": "Order"
}

Returns field descriptors with physical column names (Hibernate naming strategy), join columns, and index metadata.

Example: run_select

{
  "jpql": "SELECT u.email FROM User u WHERE u.active = true",
  "maxResults": 50
}

Blocked keywords: UPDATE, DELETE, INSERT, MERGE, DDL, etc.

Quick start

1. Add the starter (Spring Boot 3.x, Java 21+)

<dependency>
    <groupId>io.github.nullpoint3rdev</groupId>
    <artifactId>mcp-jpa-spring-boot-starter</artifactId>
    <version>0.3.0</version>
</dependency>

Requires an existing EntityManagerFactory (e.g. from spring-boot-starter-data-jpa).

2. Enable MCP (opt-in — disabled by default)

mcp:
  jpa:
    enabled: true
    endpoint: /mcp
    persistence-unit-name: default

3. Start the app

Look for this log line:

MCP JPA HTTP server ready endpoint=/mcp pu=default

4. Verify

curl -i http://localhost:8080/mcp

A non-404 response means the servlet is registered (MCP protocol handshake may require an MCP client).

Cursor setup

Point Cursor at your backend MCP endpoint (local or over VPN / internal network):

~/.cursor/mcp.json

{
  "mcpServers": {
    "jpa": {
      "url": "http://your-host:8080/mcp"
    }
  }
}

Reload MCP servers in Cursor, then invoke list_entities in chat.

{
  "mcpServers": {
    "jpa": {
      "url": "http://your-host:8080/mcp",
      "headers": {
        "Authorization": "Basic bWNwOnlvdXItc2VjcmV0"
      }
    }
  }
}

Generate Base64: echo -n 'mcp:your-secret' | base64

Configuration

All properties under mcp.jpa:

Optional HTTP Basic security

Requires spring-boot-starter-security on the classpath.

spring:
  autoconfigure:
    import: io.github.nullpoint3rdev.mcpjpa.spring.McpJpaSecurityAutoConfiguration

mcp:
  jpa:
    enabled: true
    security:
      enabled: true
      username: mcp
      password: ${MCP_JPA_PASSWORD}

Only /mcp is protected; your existing security config remains unchanged.

Security

mcp-jpa is read-only by design, but schema metadata is still sensitive.

Health checks should use /actuator/health on your management port — not /mcp.

STDIO (local development)

For local MCP without HTTP, use the core launcher with META-INF/persistence.xml:

export MCP_JPA_PERSISTENCE_UNIT=default
java -cp ... io.github.nullpoint3rdev.mcpjpa.server.McpJpaStdioLauncher

Example application

git clone https://github.com/nullpoint3rdev/mcp-jpa.git
cd mcp-jpa
mvn install
mvn -pl mcp-jpa-example spring-boot:run

MCP endpoint: http://localhost:8080/mcp

Build from source

mvn clean test
mvn install

Production checklist

□ Add mcp-jpa-spring-boot-starter dependency (from Maven Central or GitHub Packages)
□ mcp.jpa.enabled=true in a non-production profile only (or restrict by network)
□ Deploy backend; confirm log "MCP JPA HTTP server ready"
□ curl http://<host>:<backend-port>/mcp
□ Configure Cursor mcp.json
□ Secure /mcp (Basic auth or Spring Security)
□ Keep management (health/metrics) on a separate port

Roadmap

• Maven Central release 0.3.0
• MCP servers registry listing
• Native SQL read-only tools (separate security profile)
• EclipseLink compatibility tests

Contributing

Issues and pull requests are welcome. Please run mvn clean test before submitting a PR.

License

Apache License 2.0 — see LICENSE.