LoadMcpWithContext

Go · module github.com/muthuishere/toolnexus/golang · SPEC §2 · golang/mcp.go

func LoadMcpWithContext(ctx context.Context, input any, waitFor ...func(Request) (Answer, error)) (*McpSource, error)

The context-aware entry point. ctx propagates through every connect, initialize, and list call (and bounds the streamable-HTTP → SSE fallback). A per-server timeout within budget marks only that server failed and the build continues — the same isolation as LoadMcp. A parent cancellation or deadline is different: it aborts the whole load, closes every client that did connect, and LoadMcpWithContext returns ctx.Err(). LoadMcp keeps its simpler signature and delegates here with context.Background().

When to use it

Reach for LoadMcpWithContext whenever the load itself needs a budget or an external cancellation trigger — a request-scoped context in a server handler, a CLI command with a --timeout flag, or a shutdown signal that should stop connecting to MCP servers immediately rather than waiting for every one to time out on its own.

Why this and not the alternative

Examples

1. A generous budget for the shared fixture

package main

import (
  "context"
  "fmt"
  "log"
  "os"
  "path/filepath"
  "time"

  toolnexus "github.com/muthuishere/toolnexus/golang"
)

func main() {
  fixture := filepath.Join(os.Getenv("TOOLNEXUS_REPO"), "examples", "mcp.json")

  ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
  defer cancel()

  src, err := toolnexus.LoadMcpWithContext(ctx, fixture)
  if err != nil {
    log.Fatal(err)
  }
  defer src.Close()

  if src.Status["example-remote"] != toolnexus.StatusDisabled {
    log.Fatalf("expected example-remote disabled, got %v", src.Status["example-remote"])
  }

  fmt.Println("ok: loaded under a bounded context")
}

2. A cancelled parent context aborts the whole load

Cancel ctx before the call even starts — no server gets a chance to connect, and the returned error is ctx.Err() itself, not a per-server failure.

package main

import (
  "context"
  "errors"
  "fmt"
  "log"

  toolnexus "github.com/muthuishere/toolnexus/golang"
)

func main() {
  config := toolnexus.McpConfig{
    "everything": toolnexus.ServerConfig{
      Type:    "local",
      Command: []string{"npx", "-y", "@modelcontextprotocol/server-everything"},
    },
  }

  ctx, cancel := context.WithCancel(context.Background())
  cancel() // cancelled before LoadMcpWithContext even runs

  src, err := toolnexus.LoadMcpWithContext(ctx, config)
  if err == nil {
    log.Fatal("expected a context error")
  }
  if !errors.Is(err, context.Canceled) {
    log.Fatalf("expected context.Canceled, got %v", err)
  }
  if src != nil {
    log.Fatal("expected a nil McpSource on abort")
  }

  fmt.Println("ok: aborted the whole load with", err)
}

3. A disabled server is reported without ever needing the budget

Disabled servers are skipped before any connection attempt — a small, live deadline is plenty, because nothing actually races against it.

package main

import (
  "context"
  "fmt"
  "log"
  "time"

  toolnexus "github.com/muthuishere/toolnexus/golang"
)

func main() {
  disabled := true
  config := toolnexus.McpConfig{
    "off": toolnexus.ServerConfig{
      Type:     "local",
      Command:  []string{"unused"},
      Disabled: &disabled,
    },
  }

  ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
  defer cancel()

  src, err := toolnexus.LoadMcpWithContext(ctx, config)
  if err != nil {
    log.Fatal(err)
  }
  defer src.Close()

  if src.Status["off"] != toolnexus.StatusDisabled {
    log.Fatalf("expected 'off' disabled, got %v", src.Status["off"])
  }

  fmt.Println("ok: disabled server reported as", src.Status["off"])
}

Parameters

Parameter	Type	What it does
`ctx`	`context.Context`	Bounds connect + initialize + list for every server; cancellation aborts the whole build.
`input`	`any`	Anything `ParseMcpConfig` accepts.
`waitFor`	`...func(Request) (Answer, error)`	Optional (variadic) host resolver for MCP elicitation (§10).