Define and document the public Python SDK API surface

[dgenio]

Description

Summary

The Python SDK exposes a variety of classes and functions across packages and submodules. Some are clearly meant to be public, others are internal but not marked as such. Tests and user code sometimes rely on internals (e.g. private attributes).

This makes it hard for users to know what is safe to depend on and hard for maintainers to evolve internals without risking breakage.

Problems

• Ambiguous boundaries: It’s not always clear which symbols in mcp.* and subpackages are part of the supported public API.
• Private attribute usage: Some tests/examples access internal attributes (e.g. _mcp_server), which blurs the line between public and internal.
• Versioning risk: Changes to internal structures can accidentally turn into breaking changes for users who imported them directly.

Proposal

1. Define an explicit public API

   • Use __all__ and/or a mcp.public (or similar) module to list what is considered stable public API.
   • Document the intended public surface in the README or a dedicated “API Reference”.

2. Mark internals clearly

   • Move clearly internal modules into an _internal subpackage where possible.
   • Use leading underscores and documentation to indicate non-public attributes.

3. Gradual tightening

   • Update examples and tests to use only public APIs where feasible.
   • Where users are expected to interact with lower-level constructs, expose them via documented, stable paths.

Why this matters

• Stability: Users can rely on documented APIs without fear of accidental breakage.
• Refactorability: Internal changes become safer when the public surface is well-defined.
• Onboarding: New users can quickly see which APIs are meant for them.

Acceptance criteria

• A documented list of public, supported APIs for the Python SDK.
• Internal modules/types are clearly marked (e.g., _internal packages) where appropriate.
• Examples and tests avoid relying on private attributes when a public alternative exists.
• Future changes can be evaluated against this public surface for compatibility.

References

No response

[Kludex]

This is valid. I think we should review all the public/private API that we have.

[domdomegg]

Coming here from #1508 and #1617 as this now seems to be the open issue tracking import performance.

I wanted to share some profiling data that suggests this can be quite painful - we found import mcp.types takes 3+ seconds on a 64-core Xeon Platinum with 247GB RAM (from a cold start, e.g. not in cache), and pulls in 730 modules.

Cumulative import times from a cold-start python -X importtime trace:

  3137318 us | mcp.types          (total)
  2394090 us | mcp.server
  2270786 us | mcp.server.fastmcp
  1562150 us | mcp.server.lowlevel
   424784 us | mcp.client.session
   243315 us | mcp.client.experimental
   176631 us | mcp.client.stdio

The server and client stacks dominate. These are all pulled in by __init__.py eagerly importing them:

from .client.session import ClientSession
from .client.session_group import ClientSessionGroup
from .client.stdio import StdioServerParameters, stdio_client
from .server.session import ServerSession
from .server.stdio import stdio_server

None of these are needed when user code only does from mcp.types import Tool (or similar). Making __init__.py lazy (via __getattr__) could help here by avoiding importing the server/client stacks when they're not actually used, but of course open to other solutions that achieve the same goal!

[Kludex]

Is the above on main? If not, try on main, please.

[dgenio]

Following up on @Kludex's question from Jan 27 ("Is the above on main?") — yes, the slow import is still present on current main (commit 0d1031d).

Profiling data — python -X importtime -c "import mcp.types" on main:

Environment: Python 3.13.12, Windows 11, standard laptop (warm filesystem cache)
Total modules loaded: ~1607

Cumulative import times (selected):
  1,911,107 us | mcp.types          (total)
  1,910,983 us | mcp
  1,861,262 us | mcp.client
  1,861,309 us | mcp.client.client
    281,618 us | mcp.client.client  (inner)
    266,160 us | mcp.client._memory
    264,592 us | mcp.server
     48,587 us | mcp.client.session_group
     43,663 us | mcp.os.win32.utilities
      7,929 us | mcp.client.streamable_http
      6,094 us | mcp.client.session

The entire server + client + os stacks are pulled in eagerly by mcp/__init__.py even when the user only does from mcp.types import Tool. On a warm cache on modern hardware the total is ~1.9s — consistent with what @domdomegg reported.

The root cause is the eager imports in __init__.py:

from .client.session import ClientSession
from .client.session_group import ClientSessionGroup
from .client.stdio import StdioServerParameters, stdio_client
from .server.session import ServerSession
from .server.stdio import stdio_server

None of these are needed for mcp.types.

---

I'm interested in helping with this issue. I'd be happy to work on a scoped sub-task — for example, auditing mcp/__init__.py to define what should be in __all__ and proposing a clean public API surface as a starting point. Happy to defer to whatever direction @felixweinberger has in mind to avoid overlapping work.