For Developers

Server URL: https://apps.gomarble.ai/mcp-api/sse
Authentication: OAuth 2.0 with account authorization required
Protocol: SSE-based (Server-Sent Events) - not Streamable HTTP

Sample Implementation

Here's a complete example using the FastMCP client library to connect to the Marble MCP server:

import asyncio
import logging
from pathlib import Path
from fastmcp import Client
from fastmcp.client.auth import OAuth

# Set up logging to see what's happening
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def main():
    # Configure OAuth with the MCP server URL
    oauth = OAuth(
        mcp_url="https://apps.gomarble.ai/mcp-api/sse",
        scopes=["read", "write"],  # Adjust scopes as needed
        client_name="FastMCP OAuth Client",
        token_storage_cache_dir=Path.home() / ".fastmcp" / "oauth-mcp-client-cache"
    )

try:
        # Create client with OAuth authentication
        async with Client("https://apps.gomarble.ai/mcp-api/sse", auth=oauth) as client:
            logger.info("OAuth client connected successfully")
            # Test the connection
            await client.ping()
            logger.info("Server ping successful")
            # List available tools
            tools = await client.list_tools()
            logger.info(f"Available tools: {len(tools.tools)}")
            for tool in tools.tools:
                logger.info(f" - {tool.name}: {tool.description}")
            # List available resources
            resources = await client.list_resources()
            logger.info(f"Available resources: {len(resources.resources)}")
            for resource in resources.resources:
                logger.info(f" - {resource.uri}: {resource.name}")
            # List available prompts
            prompts = await client.list_prompts()
            logger.info(f"Available prompts: {len(prompts.prompts)}")
            for prompt in prompts.prompts:
                logger.info(f" - {prompt.name}: {prompt.description}")
    except Exception as e:
        logger.error(f"Error connecting to MCP server: {e}")
        raise

if __name__ == "__main__":
    asyncio.run(main())

For more details on FastMCP OAuth implementation, see: FastMCP OAuth

Client Implementation Requirements

Technical Prerequisites

• SSE Support: Your MCP client must support Server-Sent Events (SSE) based servers
• OAuth 2.0 Flow: Implement OAuth authentication handling
• HTTPS: All communications must use encrypted HTTPS connections
• Rate Limiting: Implement client-side rate limiting (25 requests per minute per user)

Authentication Implementation

The server uses OAuth 2.0 for secure authentication. Your client must:

1. Handle OAuth authentication flows
2. Manage access tokens with limited lifetime and scope
3. Implement token refresh mechanisms
4. Handle authentication errors gracefully

Connection Configuration

{
    "server_url": "https://apps.gomarble.ai/mcp-api/sse",
    "authentication": "oauth2",
    "protocol": "sse"
}

Development Best Practices

Error Handling

• Authentication Errors: Implement graceful handling for auth failures
• API Calls: Use proper error handling for all API interactions
• Connection Issues: Handle network connectivity problems
• Rate Limiting: Implement exponential backoff for rate limit hits

Performance Optimization

• Caching: Cache responses when appropriate to improve performance
• Rate Limiting: Use client-side rate limiting to prevent API abuse
• Connection Management: Maintain stable SSE connections

Debugging and Troubleshooting

Common Development Issues

Connection Issues

Symptoms:

• Failed SSE connections
• Timeout errors
• Protocol mismatches

Solutions:

1. Verify SSE protocol support in your client
2. Check network connectivity to https://apps.gomarble.ai/mcp-api/sse
3. Ensure HTTPS handling is correct
4. Validate connection parameters

Rate Limiting Issues

Symptoms:

• HTTP 429 responses
• Request throttling
• Performance degradation

Solutions:

1. Implement proper rate limiting (25 requests/minute)
2. Add exponential backoff
3. Cache responses to reduce API calls
4. Monitor request frequency

Security Considerations for Developers

Implementation Requirements

• OAuth 2.0: Proper implementation of OAuth authentication flow
• HTTPS Only: All communications must use encrypted connections
• Token Management: Secure storage and handling of access tokens
• Scope Validation: Respect user permission boundaries

Support Resources

Developer Support

When seeking technical support, provide:

• Client Implementation Details: Programming language, framework, version
• Error Messages: Complete error logs and stack traces
• Connection Configuration: Your client's MCP server configuration
• Reproduction Steps: Detailed steps to reproduce the issue
• Expected vs Actual Behavior: Clear description of the problem

Technical Support Channels

• Email Support: Contact technical support with implementation questions at admin@gomarble.ai
• Documentation: Reference this guide for implementation details.