Proposal: Session and authentication context for tools

[hemanth]

Context

WebMCP tools often need access to user authentication state. The proposal should address how tools access session context.

Problem

In our implementation bridging MCP servers to WebMCP, we needed to:

1. Store authentication tokens (OAuth, API keys)
2. Maintain MCP session IDs across tool calls
3. Handle token refresh
4. Pass credentials with each tool execution

Currently, each tool must manage this independently:

// Each tool needs auth context - no standard pattern
const tools = mcpTools.map(tool => ({
  name: tool.name,
  execute: async (args) => {
    // Tool must know about auth - breaks encapsulation
    const headers = auth.getHeaders();
    headers['Mcp-Session-Id'] = sessionId;
    
    return fetch(serverUrl, { headers, ... });
  }
}));

Proposal

A standard way to provide session/auth context to tools:

// Option A: Context parameter in execute
navigator.modelContext.provideContext({
  tools: [{
    name: "create_order",
    requiresAuth: true, // Declarative auth requirement
    execute: async (args, context) => {
      // context.session - page session info
      // context.user - authenticated user (if any)
      // context.credentials - for authorized operations
      
      return await createOrder(args, context.credentials);
    }
  }]
});

// Option B: Separate auth configuration
navigator.modelContext.setAuthContext({
  type: 'bearer',
  token: accessToken,
  refresh: async () => { /* refresh logic */ }
});

// Option C: Per-tool auth scopes
navigator.modelContext.provideContext({
  tools: [{
    name: "read_profile",
    scopes: ["profile:read"],
    execute: async (args) => { ... }
  }, {
    name: "update_profile", 
    scopes: ["profile:write"],
    execute: async (args) => { ... }
  }]
});

Use Cases

1. E-commerce: Tools need user's cart/account context
2. Document editing: Tools need access to user's files
3. API integrations: Tools need API credentials
4. Multi-tenant apps: Tools need tenant context

Security Considerations

• Credentials should not be exposed to agents
• Auth context should be scoped per-tool if needed
• Token refresh should happen transparently
• Failed auth should surface appropriate errors

Benefits

1. Clean separation of auth from tool logic
2. Standardized auth error handling
3. Support for OAuth refresh flows
4. Declarative auth requirements for tool discovery

This supports the proposal's goal of leveraging existing web app authentication rather than requiring separate agent auth flows.