MCP Connection Guide
Connect engineering tools, assistants, automations, and controlled external systems to the RaffsSync Platform through the MCP layer using a disciplined model for authentication, capability exposure, routing, and auditability.
What MCP is for
The Model Context Protocol layer is the controlled technical bridge between RaffsSync and external reasoning, orchestration, or developer-facing tooling. It is designed for structured access to approved operations, context, and actions — not as a loose public endpoint bucket.
Typical use cases
- Internal tooling for engineering, support, and operations teams
- Assistant integrations that need governed access to platform functions
- Developer diagnostics and controlled observability workflows
- Orchestration bridges between approved automation systems and RaffsSync
Browser-facing documentation endpoint
On standard browser ports, the MCP subdomain is documentation-first. This gives technical users a stable, human-readable entry point for setup guidance, security expectations, and operational rules.
https://mcp.raffssync.io/Non-browser ports and internal service paths are handled separately by the relevant MCP runtime and access model. Public web behaviour and endpoint/runtime behaviour are intentionally not the same thing.
Connection model
MCP access should be treated as a capability-controlled connection, not a generic shell. A client connects, authenticates, receives an approved capability surface, and only then invokes permitted tools or resources.
Expected flow
- Identify the MCP environment and intended use case
- Authenticate with approved credentials
- Receive scoped capabilities
- Call allowed tools or resources
- Log, trace, and audit requests
Authentication and trust
Authentication should always be explicit, scoped, and revocable. Production MCP access must be associated with a specific actor class, environment, and operational purpose.
Recommended controls
- Short-lived tokens where practical
- Environment scoping (production vs staging)
- Role / capability restrictions
- Per-client audit identity
- Rotation and revocation support
Security expectations
MCP should expose only the minimum approved surface. Treat every action as if it may affect production state, customer data, or platform integrity.
Security rules
- Least privilege by default
- Explicit tool allowlists
- Strong separation between read and write capabilities
- Tenant/customer boundary awareness
- Auditability for all sensitive actions
If a client does not need a capability, it should not be visible, much less callable.
Operational boundaries
Technical teams should decide up front what the MCP connection is allowed to do in each environment. Do not mix exploratory diagnostics, administrative mutation, and production automation in one uncontrolled profile.
Suggested separation
- Read-only support profile
- Developer diagnostic profile
- Controlled write/admin profile
- Automation runtime profile
Transport and endpoint design
The browser-facing MCP page is for documentation. Actual runtime transport may vary by environment, deployment pattern, and security posture.
Design principles
- Human docs on 80/443 for discoverability and onboarding
- Runtime services separated from public brochure/docs presentation
- Clear distinction between connection instructions and live execution surfaces
- Predictable endpoint ownership per environment and use case
Recommended developer checklist
- Confirm environment and intended capability scope
- Obtain the correct credentials and rotation rules
- Verify logging and request tracing expectations
- Test against non-production first
- Validate failure handling, retries, and timeouts
- Document the approved command/resource surface before rollout
What technical teams usually need
- Connection purpose and environment boundaries
- Authentication model and credential lifecycle
- Allowed tools, resources, and actions
- Error behaviour and traceability rules
- Rate, timeout, and retry expectations
- Change management and rollback expectations