RFC: Migrating MCP Registry from MongoDB to PostgreSQL

[sambhav]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

RFC: Migrating MCP Registry from MongoDB to PostgreSQL

Summary

This RFC proposes migrating the MCP Registry from MongoDB to PostgreSQL.

Background

The MCP Registry is currently implemented using MongoDB as its database backend. The project is in early development stages with no production deployments, making this an opportune moment to reconsider our database technology choice before wider adoption.

Motivation

Several factors motivate this proposed change:

1. Licensing Concerns: MongoDB's SSPL license restricts third-party service offerings, potentially limiting our hosting options.
2. Deployment Flexibility: PostgreSQL is available on more cloud platforms with consistent behavior across providers.
3. Data Integrity Requirements: As a registry, data consistency and ACID compliance are critical.
4. Performance for Our Workload: PostgreSQL may provide better query performance for our specific access patterns.
5. Go Language Ecosystem: Strong PostgreSQL support in the Go ecosystem.
6. Timing Advantage: With no existing users, we can make this change now without complex migration procedures.

Technical Details

Data Modeling Options in PostgreSQL

PostgreSQL offers multiple approaches that can accommodate our needs:

1. JSONB for Document Storage:

   • Store JSON documents similar to MongoDB's approach
   • Binary format improves query performance
   • Supports indexing on document properties
   • Allows for schema flexibility

2. Traditional Relational Model:

   • Normalized tables with foreign key relationships
   • Strong type checking and constraints
   • Optimized for complex queries

3. Hybrid Approach:

   • Core entities in relational tables
   • Extensible or variable attributes in JSONB columns
   • Best of both worlds for evolving schemas

Scaling and Performance

• Vertical scaling for initial growth
• Horizontal scaling via table partitioning for larger deployments
• Connection pooling for optimizing concurrent connections
• Read replicas for distributing query load

Go Implementation Considerations

• Multiple mature drivers available (pgx, pq)
• Code generation tools for type-safe queries (sqlc)
• ORM options if preferred (ent, gorm)
• Strong JSON handling aligns with Go's capabilities

Benefits

1. Better Hosting Options: More cloud providers support PostgreSQL
2. Data Integrity: Strong ACID compliance ensures registry reliability
3. Query Performance: Potentially better performance for complex queries
4. Schema Flexibility: Option to use JSONB for document-like storage or traditional tables
5. Go Ecosystem: Better tooling and type safety with Go drivers
6. Future-Proofing: Protection against licensing changes
7. Simplified Architecture: Single database rather than potentially multiple systems
8. Timing Advantage: Making this change now avoids future migration complexity

Risks and Mitigations

Risk	Mitigation
Schema design challenges	Prototype both JSONB and relational approaches
Development timeline impact	Integrate changes with current development cycle

Open Questions

1. Which PostgreSQL data modeling approach is most appropriate for the registry?

   • Primary JSONB document storage
   • Traditional relational tables
   • Hybrid approach

2. What specific performance characteristics are most important for the registry?

   • Read performance
   • Write performance
   • Query complexity support

3. What deployment environments must we support?

   • Self-hosted
   • Specific cloud providers
   • Kubernetes environments

4. Who will be responsible for implementing this change?

References

1. PostgreSQL Documentation: https://www.postgresql.org/docs/
2. PostgreSQL JSONB: https://www.postgresql.org/docs/current/datatype-json.html
3. PostgreSQL Go Driver (pgx): https://github.com/jackc/pgx

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[toby]

I agree that Postgres should ultimately be the database for the registry. I really like how Musicbrainz does their db and would opt for traditional RDBS tables. They also do a dump twice a week, which I think would be a cool idea for the registry as well.

I think for now, Mongo is ok while we work on the data that needs to be exposed to MCP Hosts for successful installation. Maybe once #3 is settled, we can model it in Postgres. We're also in discussions with a couple of platforms about hosting options, so it would be good to decide on Postgres to ensure it's available in the environment we go with.

[sambhav]

I'm not sure if the example was coincidental or contextual lol. I was a maintainer on Musicbrainz in the past 🤣 if it was coincidental, that's a small world.

[toby]

Oh wow, amazing!! That was purely coincidental. I was at Last.fm and we worked with Musicbrainz data. I see it as a heavy inspiration for this project.

[sambhav]

Hehe, it's interesting how the worlds connect. I was responsible for building their real-time relevance search system https://blog.metabrainz.org/2018/06/15/musicbrainz-search-overhaul/ so am intimately familiar with the whole DB setup and dumps.

[toby]

Very cool, glad to have your expertise involved!

[kidehen]

I agree that Postgres should ultimately be the database for the registry.

Why? What's wrong with a DBMS independent solution that still works with Postgres via ODBC?

/cc @TallTed

[indranilr]

+1 for this feature, this would at least help my organization to onboard the implementation.

[kidehen]

Why is the suggestion to move from one DBMS to another. How about a DBMS-independent approach?

[TallTed]

... as somewhat more detailed in #19 (comment)

[domdomegg]

I agree with this proposal, think it is good!

I think the reasons that are most convincing to me are:

Licensing Concerns: MongoDB's SSPL license restricts third-party service offerings, potentially limiting our hosting options.

Deployment Flexibility: PostgreSQL is available on more cloud platforms with consistent behavior across providers.

I'd also add:

• K8s friendly: It's way easier from experience to set up Postgres in K8s well (e.g. with backups, monitoring, read replicas...), than it is to do mongo well. Especially with tools like CloudNativePG. Almost all our deployment infra proposals are coalescing around something on K8s.

Would be keen for us to make a hard decision to commit or not to Postgres. Probably leaning yes given both me (Anthropic) and Toby (GitHub) already agree? And I think Tadas (PulseMCP) was open/supportive, although not sure. I'm going to go ahead assuming we're all in alignment/agreed on this, but shout if not.

[tadasant]

Yep I don't have a strong opinion on this and if I dug in I trust I'd come to the same conclusion as you guys -- I support the change

[rdimitrov]

FWIW I'm also +1 on this 👍

[bdeen-mdsol]

Alternative Approach: Support Multiple MongoDB-Compatible Backends

Summary

Instead of migrating from MongoDB to PostgreSQL, support both through MongoDB wire protocol compatibility. This solves SSPL licensing concerns while preserving existing work and requiring zero application code changes.

Proposal

The MCP Registry already uses MongoDB drivers through an abstracted database interface. Self-hosters can choose their preferred backend:

Option 1: MongoDB (Current/Default)

# Official hosted registry continues using this
docker-compose -f docker-compose.mongodb.yml up

• License: SSPL
• Best for: Full feature compatibility, production workloads
• Status: Current implementation, no changes needed

Option 2: FerretDB + PostgreSQL (New)

# For self-hosters with SSPL concerns
docker-compose -f docker-compose.ferretdb.yml up

• License: Apache 2.0 (FerretDB) + PostgreSQL License
• Best for: Organizations blocked by SSPL, PostgreSQL expertise
• Status: Drop-in replacement, production ready (v2.0 GA March 2025)

How It Works

┌─────────────────────────┐
│   MCP Registry (Go)     │
│   (MongoDB drivers)     │
└───────────┬─────────────┘
            │ Same connection string format
            │ mongodb://host:27017/mcp-registry
            │
    ┌───────┴────────┐
    │                │
    ▼                ▼
┌─────────┐    ┌──────────────┐
│ MongoDB │    │  FerretDB    │ (proxy)
│         │    │      ↓       │
└─────────┘    │ PostgreSQL + │
               │ DocumentDB   │
               └──────────────┘

FerretDB is a transparent proxy that:

1. Accepts MongoDB wire protocol connections
2. Translates to PostgreSQL queries (using DocumentDB extension)
3. Returns MongoDB-formatted responses

The application is completely unaware which backend is being used.

Implementation

Step 1: Add FerretDB Docker Compose Configuration

# docker-compose.ferretdb.yml
version: '3.8'
services:

postgres:

image: postgres:16

environment:

POSTGRES_DB: ferretdb

POSTGRES_USER: ferretdb

POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

volumes:

- postgres_data:/var/lib/postgresql/data

healthcheck:

test: ["CMD-SHELL", "pg_isready -U ferretdb"]

interval: 10s

timeout: 5s

retries: 5
ferretdb:

image: ghcr.io/ferretdb/ferretdb:2

ports:

- "27017:27017"

environment:

FERRETDB_POSTGRESQL_URL: postgres://ferretdb:${POSTGRES_PASSWORD}@postgres:5432/ferretdb

depends_on:

postgres:

condition: service_healthy
registry:

image: ghcr.io/modelcontextprotocol/registry:latest

ports:

- "8080:8080"

environment:

MCP_REGISTRY_DATABASE_URL: mongodb://ferretdb:27017

MCP_REGISTRY_DATABASE_NAME: mcp-registry

MCP_REGISTRY_COLLECTION_NAME: servers_v2

# All other env vars same as MongoDB deployment

depends_on:

- ferretdb
volumes:

postgres_data:

Step 2: Update Documentation

Add to README.md:

## Self-Hosting Options
With MongoDB (Official)
The default deployment uses MongoDB:
```bash

make dev-compose

```
With PostgreSQL via FerretDB
For organizations with MongoDB SSPL licensing concerns, you can use FerretDB

as a MongoDB-compatible proxy to PostgreSQL:
```bash

docker-compose -f docker-compose.ferretdb.yml up

```
Note: Both options use identical application code. FerretDB provides

MongoDB wire protocol compatibility with PostgreSQL backend. No code changes required.

Step 3: Add CI Testing (Optional but Recommended)

# .github/workflows/test.yml
jobs:
  test-mongodb:
    name: Test with MongoDB
    # ... existing MongoDB tests
test-ferretdb:

name: Test with FerretDB

runs-on: ubuntu-latest

services:

postgres:

image: postgres:16

env:

POSTGRES_DB: ferretdb

POSTGRES_USER: ferretdb

POSTGRES_PASSWORD: password

options: >-

--health-cmd pg_isready

--health-interval 10s

--health-timeout 5s

--health-retries 5
  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:2
    env:
      FERRETDB_POSTGRESQL_URL: postgres://ferretdb:password@postgres:5432/ferretdb
    ports:
      - 27017:27017
      
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version: '1.24'
  - name: Run tests
    env:
      MCP_REGISTRY_DATABASE_URL: mongodb://localhost:27017
    run: make test-all

That's it. No other changes needed.

Pros and Cons

Pros

✅ Zero code changes - Application code remains identical
✅ Addresses RFC motivation - Solves SSPL licensing concerns for those who need it
✅ Immediate availability - Can be implemented in days, not months
✅ User choice - Each deployment picks what fits their constraints
✅ Preserves existing work - Official hosted registry unchanged
✅ True open source option - Apache 2.0 license (FerretDB) + PostgreSQL
✅ Broader adoption - Organizations blocked by SSPL can now use MCP Registry
✅ Future-proof - Can support additional compatible backends as they emerge
✅ Low risk - No migration, just additional deployment option
✅ Battle-tested approach - Similar to how Redis→Valkey, Elasticsearch→OpenSearch work

Cons

⚠️ Not 100% MongoDB compatible - FerretDB supports core features but not everything

• Mitigation: MCP Registry uses basic CRUD operations that are well-supported

⚠️ Performance differences - May not match MongoDB for all workloads

• Mitigation: FerretDB v2.0 is 20x faster than v1.0; sufficient for registry use case

⚠️ Legal uncertainty - MongoDB claims FerretDB infringes patents (as of May 2025)

• Mitigation: This is MongoDB vs FerretDB dispute, not affecting users; FerretDB disputes claims

⚠️ Another component - Self-hosters need to run FerretDB proxy

• Mitigation: Single docker-compose file makes this transparent

⚠️ Testing required - Must validate registry works with FerretDB

• Mitigation: Can add CI tests for both MongoDB and FerretDB backends

⚠️ Documentation burden - Need to explain two deployment options

• Mitigation: Minimal - one additional docker-compose file and README section

Comparison to Full PostgreSQL Migration

Aspect	Full PostgreSQL Migration (RFC)	This Proposal
Code changes	Complete rewrite	None
Data model	Redesign to relational	Keep document model
Effort	Weeks to months	Days
Risk	High (breaking changes)	Low (additive)
Timeline	Long-term	Immediate
Hosted registry	Must migrate	No changes
Self-hosters	Must migrate	Can choose
Testing scope	Comprehensive retest	Validate compatibility
Licensing	PostgreSQL license only	Multiple options
Disruption	Significant	Minimal

About FerretDB

• Version: v2.0 GA released March 5, 2025 - production ready
• Performance: 20x faster than v1.0 using Microsoft's DocumentDB PostgreSQL extension
• License: Apache 2.0 (OSI-approved open source)
• Compatibility: MongoDB 5.0+ wire protocol
• Architecture: Stateless proxy (no MongoDB code used)
• Backing: Microsoft collaboration, active open source development
• Documentation: https://docs.ferretdb.io
• GitHub: https://github.com/FerretDB/FerretDB

FerretDB was specifically created to address MongoDB's SSPL licensing concerns:

"MongoDB abandoned its open-source roots; changing the license to SSPL - making it unusable for many open-source and early-stage commercial projects. FerretDB is here to fill that gap."

Response to RFC Concerns

"Licensing and community preference"
→ ✅ Solved. Users with SSPL concerns use FerretDB (Apache 2.0)

"Broader adoption"
→ ✅ Solved. Organizations blocked by SSPL can now self-host

"Taking advantage of early stage"
→ ✅ Achieved with minimal work, not breaking changes

"PostgreSQL benefits (mature tooling, replication)"
→ ✅ Achieved. FerretDB uses PostgreSQL backend with all its benefits

"Go implementation considerations"
→ ✅ No changes to Go code needed, just connection string configuration

Why I Think This Is Better Than Replacing MongoDB Outright

1. Risk Mitigation - Additive change, not destructive migration
2. Flexibility - Users choose based on their constraints, not forced choice
3. Time to Market - Days not months
4. Backwards Compatible - Existing deployments unaffected
5. Proven Pattern - Industry standard approach to licensing concerns
6. Vendor Independence - Multiple compatible backends available
7. Future Optionality - Can still do full migration later if data shows it's needed

Recommendation

Implement this proposal first, then evaluate full migration later if needed.

This gives the project:

1. ✅ Immediate solution to SSPL concerns
2. ✅ Flexibility for different user needs
3. ✅ No risk to existing deployments
4. ✅ Time to properly evaluate if full PostgreSQL migration is necessary
5. ✅ Real-world data on PostgreSQL performance for this use case

The registry can support both options indefinitely, or transition to PostgreSQL-only in the future if evidence shows it's beneficial.

Next Steps

If this approach is acceptable:

1. Week 1: Create and test docker-compose.ferretdb.yml configuration
2. Week 1: Validate registry operations against FerretDB locally
3. Week 2: Add CI tests for FerretDB backend
4. Week 2: Update documentation with deployment options
5. Week 2: Create example .env files for both deployments
6. Release: Announce both options as supported deployment methods

Estimated effort: 1-2 weeks of work vs. months for full migration

---

Questions for discussion:

1. Does this approach address the licensing concerns that motivated the RFC?
2. Are there specific MongoDB features the registry uses that we should verify FerretDB supports?
3. Should we make FerretDB an officially supported option or keep it community-maintained?
4. What's the minimum acceptable test coverage for the FerretDB deployment option?

Would this alternative approach work for the community's needs?

[TallTed]

This loose-er binding would be better than simply changing the existing tight binding from MongoDB to PostgreSQL, but it's not truly loose binding.

Loose binding could be achieved by binding to ODBC, using either iODBC or UnixODBC SDK components. This would enable use of any DBMS with an ODBC driver (or, through an ODBC-to-JDBC Bridge driver, any DBMC with a JDBC driver).

Relatively loose binding could be achieved via an MCP Server for ODBC, and an ODBC (or JDBC, as above) driver for the currently-chosen backend DBMS.

[kidehen]

Is there a reason why this couldn't simply be DBMS independent via the following?

1. ODBC -- this works with any ODBC drivers/connectors on the deployment host
2. MCP Server for ODBC -- this works with any ODBC data source names on the deployment host

[domdomegg]

Sadly because SQL isn't standardized very well, you end up having problems between the databases (e.g. we use pg_advisory_lock which is not supported in MySQL or Oracle).

Additionally ODBC drivers are not super well supported and tested from Golang - I'm sure some work, but it'll still likely have a lot of weird edge cases we don't want to support.

Also see comment below about this registry project goals.

[domdomegg]

Heya, on the recent discussion about supporting multiple DBs see this from the FAQ:

Can I use the code here to run my own registry instance?
The registry implementation here is not designed for self-hosting, but you're welcome to try to use it/fork it as necessary. Note that this is not an intended use, and the registry maintainers cannot provide any support for this at this time.

We discussed yesterday at the MCP summit building a better registry for self-hosting, that could more easily aggregate MCP servers from different sources. E.g. for internal private deployments. Perhaps we should start another thread about this? (cc @rdimitrov who has more context here)

[domdomegg]

Closing this discussion as we did end up implementing the RFC to move from MongoDB to PostgresSQL, I think discussions regarding self-hosting with other databases probably should go into a separate discussion. Again, this is not currently supported but we'd be open to a separate project pursuing this (perhaps with better controls for moderation, filtering and aggregating from multiple registries - and less on publishing itself. i.e. features more tailored to subregistries).