Getting Started¶

This guide will help you set up the Android MCP SDK in your Android project and get your first MCP server running.

⚠️ This library is intended for debug builds and development environments only. Do not include in production apps.

Prerequisites¶

Android Studio Arctic Fox or later
Minimum SDK 29 (Android 10)
Kotlin 1.9.0 or later

Installation¶

Gradle Setup¶

Add the library to your app module's build.gradle.kts:

dependencies {
    debugImplementation("dev.jasonpearson:mcp-android-sdk:1.0.0")  // Debug builds only
}

Then in your build.gradle.kts:

dependencies {
    debugImplementation(libs.mcp.android.sdk)
}

Quick Setup¶

Option 1: Automatic Initialization and Startup¶

The simplest way to get started - the library automatically initializes and starts the server without any code needed. Since this is intended for debug variants only, it's less common you'd want this SDK to be deferred to some DI framework startup initializer.

// No code needed! Just add the dependency and the MCP server
// automatically initializes and starts via AndroidX Startup

📱 See Complete Example →

The Simple Sample demonstrates:

Zero-configuration setup
Automatic initialization and startup
Basic custom tools
Transport testing

Option 2: Deferred startup, probably via Dependency Injection¶

For apps using Hilt, integrate MCP through dependency injection for better testability and configuration management.

@Module
@InstallIn(SingletonComponent::class)
object McpModule {
    @Provides @Singleton
    fun provideMcpServerManager(@ApplicationContext context: Context): McpServerManager {
        return McpStartup.initializeManually(context)
    }
}

🔧 See Complete Implementation →

The Hilt Integration Sample demonstrates: - Manual initialization via Hilt DI - Configuration management through dependency injection - Debug environment patterns - Easy testing and mocking

Option 3: Other DI Frameworks¶

Similar patterns work with Koin, Dagger, and other dependency injection frameworks.

🏗️ More DI samples coming soon!

Sample Applications¶

Instead of maintaining potentially outdated code examples in this documentation, we provide working sample applications that you can build, run, and learn from:

Sample	Purpose	Target Use Case
Simple	Basic automatic setup	Prototypes, simple apps
Hilt Integration	Debug DI patterns	Debug builds with Hilt

Building and Running Samples¶

# Build all samples
./gradlew assembleDebug

# Install and test a specific sample
./gradlew :samples:simple:installDebug
adb logcat | grep MCP

First Steps¶

Check Server Status¶

After setup, verify everything is working:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Check if MCP is initialized
        if (McpStartup.isInitialized()) {
            val manager = McpStartup.getManager()
            Log.d("MCP", "Server running: ${manager.isServerRunning()}")
        }
    }
}

📖 See complete MainActivity examples in samples →

Test Built-in Tools¶

The SDK includes several built-in Android tools:

lifecycleScope.launch {
    val manager = McpStartup.getManager()
    val deviceInfo = manager.executeAndroidTool("device_info", emptyMap())
    Log.d("MCP", "Device info: ${deviceInfo.result}")
}

Testing Your Setup¶

Using adb Port Forwarding¶

The Android MCP SDK includes comprehensive ADB port forwarding support for connecting MCP clients from your workstation:

# Quick setup with automated scripts
./scripts/adb_testing/setup_port_forwarding.sh

# Test the HTTP/SSE endpoint
curl http://localhost:8080/mcp

# Clean up when done
./scripts/adb_testing/cleanup_port_forwarding.sh

📡 Complete ADB Port Forwarding Guide →

The ADB documentation covers:

✅ Automated setup scripts and testing
✅ Manual configuration options
✅ Troubleshooting common issues
✅ Integration with MCP clients
✅ Performance and reliability testing

Sample Apps for Testing¶

The samples include comprehensive testing features:

# Build and install any sample
./gradlew :samples:simple:assembleDebug
./gradlew :samples:simple:installDebug

# Check logs for MCP initialization and sample app behavior
adb logcat | grep -E "(MCP|SampleMcp|HiltMcp)"

🔍 Complete testing guide in samples →

Configuration Options¶

Automatic Configuration¶

By default, the library automatically configures AndroidX Startup. No manifest changes needed.

Disabling Automatic Initialization¶

To disable automatic initialization (for DI framework integration):

<application>
    <provider
        android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        tools:node="merge">
        <meta-data
            android:name="dev.jasonpearson.mcpandroidsdk.McpServerManagerInitializer"
            tools:node="remove" />
    </provider>
</application>

📋 See complete manifest examples in samples →

Common Issues¶

Initialization Fails¶

Minimum SDK: Ensure your app targets API 29 or higher
AndroidX Startup: Make sure AndroidX Startup is properly configured
Permissions: Check if any additional permissions are needed

Server Won't Start¶

Check logs: Look for error messages in Logcat
Port conflicts: Ensure ports 8080 and 8081 aren't being used by other apps
Lifecycle state: Make sure your app is in the foreground

Transport Issues¶

Port forwarding: Verify adb port forwarding is set up correctly
Firewall: Check if any firewall is blocking the connections
Network: Ensure your development machine can reach the Android device

🔧 See troubleshooting examples in samples →

Next Steps¶

Once you have the basic setup working:

Choose a Sample App - Find the pattern that fits your use case
Add Custom Tools - Create your own MCP tools
Configure Resources - Expose app data as MCP resources
Set Up Transports - Configure WebSocket and HTTP transports
Explore API Reference - Complete API documentation

Dependencies¶

The library includes these dependencies automatically:

io.modelcontextprotocol:kotlin-sdk:0.5.0 - Main MCP Kotlin SDK
io.modelcontextprotocol:kotlin-sdk-jvm:0.5.0 - JVM-specific implementation
androidx.startup:startup-runtime:1.2.0 - AndroidX Startup for initialization