Servers

​

Overview

​

Core MCP Server Building Blocks

• Tools — actions the client or agent can perform. Each tool has a schema for inputs and outputs (e.g. sendEmail(to, subject, body) or createCalendarEvent(title, start, end)).
• Resources — structured data sources available to clients, identified by URIs. (e.g. file:///notes/project.md, calendar://events/2025, or vault://secret/{name}.)
• Prompts — reusable workflows or templates that guide how tools and resources are used together.
  (e.g. triageSupportTicket(ticket_id) or planVacation(destination, duration)).

​

Server Hierarchy and Ownership

• Organizations own servers, registries, deployments, variables, secrets, and memberships.
• Servers belong to exactly one organization and live under a namespace like @org-slug/server-name.
• Server versions are immutable snapshots of a server, tied back to the organization.
• Deployments are running instances of specific server versions.
• Registries are owned by organizations. They act as curated collections of servers for teams or projects.

​

Relationship model

Pylee Organization
├── Servers (0 to many)
│   ├── Server Versions (immutable, org-owned)
│   │   └── Variables & Secrets Placeholders
│   │   └── Deployments (instances of versions)
├── Registries (0 to many)
│   ├── Server Versions (many-to-many relationship)
│   └── Variables & Secrets
└── Memberships & Access Control
└── Variables & Secrets

​

Talking about MCP “servers”

1. Server specification — a manifest file that describes what the server can do (its tools, resources, and prompts) and configuration (connection type, transportation type, and arguments). Think of this as a blueprint.
   Example: a JSON manifest listing an issue:create tool and a projects://roadmap resource via a remote HTTP server.
2. Server implementation — the actual code, package, or container that fulfills the specification. This is what you, as a developer, write.
   Example: a Python package that knows how to create issues in GitHub.
3. Running instance — a live process that clients can connect to. This is the “server” in the classic sense.
   Example: a process running on your laptop, or an HTTP server hosted in your cloud.

​

Deployment, Connection, and Transport

1. Deployment / Location — Where is the server running?
   • Local: runs on the same machine as the client (e.g. your IDE spawns it).
   • Remote: runs elsewhere (a container, VM, or hosted service).
2. Connection / Entry Point — How do I reach it?
   Think of this as the connection method, startup mode, or endpoint type.
   • Package (start on demand): the client starts a child process server by running a command.
     Example: ["python", "-m", "my_mcp"]
   • Remote (prerunning): the client connects to a server already running at a URL.
     Example: https://my-server.acme.com
3. Transport — Once connected, how do messages flow?
   • stdio: when one program starts another, they talk through built-in text channels (stdin/stdout) - like how terminals and editors communicate with tools they launch.
   • http/sse: network-friendly web protocols; common in production.

• A local package is often paired with stdio, but could also spawn an HTTP/SSE server that the client then connects to.
• A remote almost always uses HTTP/SSE, since stdio only works with parent/child processes.
• A pre-running server can still be on your local machine at http://localhost - useful when testing servers during development.

​

How Servers Map into Pylee

• Entry point — how clients connect (either a Package launched locally via STDIO, or a Remote at a URL over HTTP/SSE).
• Capabilities — the tools, resources, and prompts exposed.
• Placeholders — configuration keys (like API_KEY, BASE_URL) that Pylee fills in at runtime.

​

Configuration: Connection Type, Versions, & Placeholders

​

Versioning

• Versions are editable until published; after publish they’re immutable.
• Any alphanumeric string is accepted as a version label.
• Best practice: use semantic versioning (1.2.0) to signal breaking, minor, and patch changes.
• Pinning makes CI, IDEs, and agents more reliable.
• Immutable versions make rollbacks simple.

​

Placeholders

1. Registry values — highest priority, often used to scope per team or project.
2. Organization values — defaults shared across the org.

​

Visibility and Sharing

• Private — default. Visible only inside your organization and its registries.
• Public — listed in the Pylee Marketplace, and optionally mirrored to Anthropic’s global registry.

​

Deployment and running instances

​

1. Run locally (on your laptop)

• Where it runs: directly on your machine.
• How it works:
  • If the server is a package (stdio), the client launches it as a local process. No network port is used — the client and server just talk through stdin/stdout.
  • If the server is a remote (HTTP/SSE), you can still run it locally on a port like http://localhost:3000. Even though it’s on your laptop, you configure it as a remote in the server spec.
• When to use it: quick iteration, debugging, or servers that need access to your local files.
• How to connect: usually via direct connect in your IDE or client. You can also use a registry if you want to share consistent settings across multiple clients.

​

2. Run in your own infrastructure

• Where it runs: in your cloud or on-prem environment (e.g., AWS, GCP, Azure, or your own servers).
• How it works:
  • Always configured as a remote (HTTP/SSE).
  • The same process you tested on localhost:3000 during development can be deployed behind your own public or internal URL. Update the server version in Pylee to point to the new URL.
• When to use it: when your team already manages hosting and scaling.
• How to connect: recommended via registries (for audit and governance), but direct connect is still possible for testing.

​

3. Run on Pylee (hosted deployment)

• Where it runs: Pylee builds and runs your implementation for you in a managed environment.
• How it works:
  • Pylee deploys it as a remote (HTTP/SSE).
  • You don’t need to assign a URL — Pylee issues a secure one automatically.
  • Variables and secrets are injected safely at runtime.
• When to use it: when you want a production-ready server without setting up infrastructure.
• How to connect: usually through registries, which add visibility, approvals, and version pinning.

​

Localhost during development

1. Create or select a server version.
2. Register localhost:3000 as the remote.
3. Run your implementation code locally and connect to it.
4. Optionally use a tool like ngrok if you need to expose it temporarily for external clients.
5. Later, swap the remote URL for a production endpoint (your own infra or Pylee-hosted).

• A “remote” just means “a server with an HTTP/SSE endpoint.” That endpoint can point to localhost during dev or a hosted URL in production.
• A stdio server is always a package and never runs on a port.

​

Pylee Usage

• Direct connection — attach to one server at a time. Simple for testing or focused tasks.
• Registry connection — attach through a registry, which can include many servers. Registries also provide approvals, pinning, and audit. This is the recommended way for production.

​

Putting it together

1. Write your implementation code.
2. Run it locally:
   • as a package (stdio), or
   • as a remote (HTTP/SSE) bound to localhost:3000.
3. Create a server version in Pylee, marking it as a package or remote.
4. Promote the same implementation:
   • run it in your own infra and update the remote URL, or
   • deploy on Pylee and use the URL provided for you.
5. Pin the version in a registry so teams connect to the same server securely with variables and secrets resolved.