externalmcp

package
v0.0.0-...-d24a8fc Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 18, 2026 License: AGPL-3.0 Imports: 41 Imported by: 0

Documentation

Index

Constants

View Source
const (
	OAuthVersionNone = "none" // No OAuth required
	OAuthVersion21   = "2.1"  // MCP OAuth with RFC 8414 discovery + dynamic registration
	OAuthVersion20   = "2.0"  // Legacy OAuth 2.0 (no AS discovery, requires static client config)
)

OAuthVersion represents the detected OAuth version/capability level.

View Source
const ProxyToolNameDelimiter = "--"

ProxyToolNameDelimiter separates the slug from the tool name in proxy tool names.

Variables

This section is empty.

Functions

func Attach

func Attach(mux goahttp.Muxer, service *Service)

func BuildHeaders

func BuildHeaders(
	systemEnv *toolconfig.CaseInsensitiveEnv,
	userConfig *toolconfig.CaseInsensitiveEnv,
	headerDefs []HeaderDefinition,
	oauthToken string,
) map[string]string

BuildHeaders constructs HTTP headers from system environment variables and user configuration.

Logic: 1. ALL system env values become headers using the appropriate header names. 2. For keys with header definitions, use the definition's HeaderName. 3. For keys without definitions, derive the header name using ToHTTPHeader. 4. User config can override values (only for keys with header definitions). 5. Empty values are skipped. 6. If oauthToken is provided, sets Authorization: Bearer <token>.

Types

type AuthRejectedError

type AuthRejectedError struct {
	RemoteURL       string
	StatusCode      int
	WWWAuthenticate string
}

AuthRejectedError is returned when an MCP server rejects authentication (401 or 403). WWWAuthenticate is populated when the server provides a WWW-Authenticate header.

func (*AuthRejectedError) Error

func (e *AuthRejectedError) Error() string

type CachedListServersResponse

type CachedListServersResponse struct {
	Key     string
	Servers []*types.ExternalMCPServer
}

CachedListServersResponse wraps a list of external MCP servers for caching.

func (CachedListServersResponse) AdditionalCacheKeys

func (c CachedListServersResponse) AdditionalCacheKeys() []string

func (CachedListServersResponse) CacheKey

func (c CachedListServersResponse) CacheKey() string

func (CachedListServersResponse) TTL

type CachedServerDetailsResponse

type CachedServerDetailsResponse struct {
	Key     string
	Details *ServerDetails
}

CachedServerDetailsResponse wraps server details for caching.

func (CachedServerDetailsResponse) AdditionalCacheKeys

func (c CachedServerDetailsResponse) AdditionalCacheKeys() []string

func (CachedServerDetailsResponse) CacheKey

func (c CachedServerDetailsResponse) CacheKey() string

func (CachedServerDetailsResponse) TTL

type CallToolResult

type CallToolResult struct {
	Content []json.RawMessage
	IsError bool
}

CallToolResult represents the result of a tool call.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents an active connection to an external MCP server.

func NewClient

func NewClient(ctx context.Context, logger *slog.Logger, remoteURL string, transportType types.TransportType, opts *ClientOptions) (*Client, error)

NewClient creates a new client connection to an external MCP server. This performs the MCP protocol initialization internally.

func (*Client) CallTool

func (c *Client) CallTool(ctx context.Context, toolName string, arguments json.RawMessage) (*CallToolResult, error)

CallTool calls a tool on the external MCP server.

func (*Client) Close

func (c *Client) Close() error

Close closes the client connection.

func (*Client) ListTools

func (c *Client) ListTools(ctx context.Context) ([]Tool, error)

ListTools lists available tools from the external MCP server.

type ClientOptions

type ClientOptions struct {
	// Authorization is the value for the Authorization header (e.g., "Bearer token").
	// If empty, no Authorization header is sent.
	Authorization string
	// Headers contains additional HTTP headers to send with each request.
	// Keys are header names, values are header values.
	Headers map[string]string
}

ClientOptions contains options for creating an MCP client.

type ExternalMCPOAuthConfig

type ExternalMCPOAuthConfig struct {
	// RemoteURL is the parsed URL of the external MCP server
	RemoteURL *url.URL
	// RegistryID is the ID of the MCP registry the server belongs to
	RegistryID string
	// Slug is the tool prefix slug (e.g., "github")
	Slug string
	// Name is the reverse-DNS server name (e.g., "ai.exa/exa")
	Name string

	// OAuth metadata from the external server
	OAuthVersion          string   // "2.1", "2.0", or "none"
	AuthorizationEndpoint string   // OAuth authorization endpoint URL
	TokenEndpoint         string   // OAuth token endpoint URL
	RegistrationEndpoint  string   // OAuth dynamic client registration endpoint URL
	ScopesSupported       []string // OAuth scopes supported by the server
}

ExternalMCPOAuthConfig contains OAuth configuration extracted from an external MCP tool that requires OAuth authentication.

func ResolveOAuthConfig

func ResolveOAuthConfig(toolset *types.Toolset) *ExternalMCPOAuthConfig

ResolveOAuthConfig returns the OAuth configuration from the first external MCP tool in the toolset that requires OAuth, or nil if none found.

type HeaderDefinition

type HeaderDefinition struct {
	Name       string // Prefixed environment variable name (e.g., "SLACK_X_API_KEY")
	HeaderName string // HTTP header to send (e.g., "X-Api-Key")
}

HeaderDefinition maps an environment variable name to an HTTP header name.

type ListServersParams

type ListServersParams struct {
	Search *string
	Cursor *string
}

ListServersParams contains optional parameters for listing servers.

type OAuthDiscoveryResult

type OAuthDiscoveryResult struct {
	Version               string // "2.1", "2.0", or "none"
	AuthorizationEndpoint string
	TokenEndpoint         string
	RegistrationEndpoint  string
	ScopesSupported       []string
}

OAuthDiscoveryResult contains the OAuth metadata discovered for an external MCP server.

func DiscoverOAuthMetadata

func DiscoverOAuthMetadata(ctx context.Context, logger *slog.Logger, wwwAuthenticate string, remoteURL string) (*OAuthDiscoveryResult, error)

DiscoverOAuthMetadata discovers OAuth configuration for an external MCP server. It parses the WWW-Authenticate header and fetches metadata from discovered URLs. If no metadata URLs are in the header, it probes standard well-known locations.

type PlanResolver

type PlanResolver func(ctx context.Context, toolURN urn.Tool, projectID uuid.UUID) (*ToolCallPlan, error)

PlanResolver resolves a tool URN to a ToolCallPlan.

type ProxyToolEntry

type ProxyToolEntry struct {
	SourceSlug string   // e.g., "slack" - used for matching
	URN        urn.Tool // URN of the proxy tool (e.g., tools:ext-mcp:slack:proxy)
}

ProxyToolEntry contains metadata needed for matching incoming tool calls to proxy tools.

type ProxyToolExecutor

type ProxyToolExecutor struct {
	// contains filtered or unexported fields
}

ProxyToolExecutor provides matching for external MCP tool names. The executor matches tool names against MCP server slugs and returns the external tool name. Actual execution happens elsewhere using the returned URN to get a plan and create a client.

func BuildProxyToolExecutor

func BuildProxyToolExecutor(logger *slog.Logger, tools []*types.Tool) *ProxyToolExecutor

BuildProxyToolExecutor creates a ProxyToolExecutor from a list of tools. Filters internally to only include external MCP tools with Type "proxy".

func (*ProxyToolExecutor) DoList

func (e *ProxyToolExecutor) DoList(
	ctx context.Context,
	projectID uuid.UUID,
	userConfig *toolconfig.CaseInsensitiveEnv,
	oauthToken string,
	loadSystemEnv SystemEnvLoader,
	resolve PlanResolver,
) ([]Tool, error)

DoList lists tools from all proxy tools in this executor. For each entry, loads system env, resolves the plan, connects to the MCP server, lists tools, and prefixes tool names with the source slug.

func (*ProxyToolExecutor) HasEntries

func (e *ProxyToolExecutor) HasEntries() bool

HasEntries returns true if this executor has any proxy tool entries.

func (*ProxyToolExecutor) MatchPlanInputs

func (e *ProxyToolExecutor) MatchPlanInputs(ctx context.Context, toolName string, projectID uuid.UUID, resolve PlanResolver) (*ToolCallPlan, error)

MatchPlanInputs checks if the given tool name belongs to any proxy tool in this executor. If matched, resolves the ToolCallPlan inputs and sets ToolName to the external tool name. Returns nil if no match (not an error). Returns error if resolver fails. Expected format: <slug>--<toolName>

type PulseBackend

type PulseBackend struct {
	// contains filtered or unexported fields
}

func NewPulseBackend

func NewPulseBackend(registryURL *url.URL, tenantID string, api conv.Secret) *PulseBackend

func (*PulseBackend) Authorize

func (p *PulseBackend) Authorize(req *http.Request) error

func (*PulseBackend) Match

func (p *PulseBackend) Match(req *http.Request) bool

type Registry

type Registry struct {
	ID  uuid.UUID
	URL string
}

Registry represents an MCP registry endpoint.

type RegistryBackend

type RegistryBackend interface {
	Match(req *http.Request) bool
	Authorize(req *http.Request) error
}

type RegistryClient

type RegistryClient struct {
	// contains filtered or unexported fields
}

RegistryClient handles communication with external MCP registries.

func NewRegistryClient

func NewRegistryClient(logger *slog.Logger, tracerProvider trace.TracerProvider, backend RegistryBackend, cacheImpl cache.Cache) *RegistryClient

NewRegistryClient creates a new registry client. The cacheImpl parameter is optional — pass nil to disable caching.

func (*RegistryClient) GetServerDetails

func (c *RegistryClient) GetServerDetails(ctx context.Context, registry Registry, serverName string) (*ServerDetails, error)

GetServerDetails fetches server details including the remote URL from the registry.

func (*RegistryClient) ListServers

func (c *RegistryClient) ListServers(ctx context.Context, registry Registry, params ListServersParams) ([]*types.ExternalMCPServer, error)

ListServers fetches servers from the given registry.

type RemoteHeader

type RemoteHeader struct {
	Name        string  `json:"name"`
	IsSecret    bool    `json:"isSecret"`
	IsRequired  bool    `json:"isRequired"`
	Description *string `json:"description,omitempty"`
	Placeholder *string `json:"placeholder,omitempty"`
}

RemoteHeader represents a header requirement from the registry.

type ServerDetails

type ServerDetails struct {
	Name          string
	Description   string
	Version       string
	RemoteURL     string
	TransportType externalmcptypes.TransportType
	Tools         []serverTool
	Headers       []RemoteHeader
}

ServerDetails contains detailed information about an MCP server including connection info.

type Service

type Service struct {
	// contains filtered or unexported fields
}

func NewService

func NewService(logger *slog.Logger, tracerProvider trace.TracerProvider, db *pgxpool.Pool, sessions *sessions.Manager, registryClient *RegistryClient) *Service

func (*Service) APIKeyAuth

func (s *Service) APIKeyAuth(ctx context.Context, key string, schema *security.APIKeyScheme) (context.Context, error)

func (*Service) ListCatalog

func (s *Service) ListCatalog(ctx context.Context, payload *gen.ListCatalogPayload) (*gen.ListCatalogResult, error)

type SystemEnvLoader

type SystemEnvLoader func(ctx context.Context, toolURN urn.Tool) (*toolconfig.CaseInsensitiveEnv, error)

SystemEnvLoader loads system environment variables for a given tool URN.

type Tool

type Tool struct {
	Name        string
	Description string
	Schema      json.RawMessage
	Annotations *ToolAnnotations
}

Tool represents a tool discovered from an external MCP server.

type ToolAnnotations

type ToolAnnotations struct {
	Title           string `json:"title,omitempty"`
	ReadOnlyHint    *bool  `json:"readOnlyHint,omitempty"`
	DestructiveHint *bool  `json:"destructiveHint,omitempty"`
	IdempotentHint  *bool  `json:"idempotentHint,omitempty"`
	OpenWorldHint   *bool  `json:"openWorldHint,omitempty"`
}

ToolAnnotations contains MCP tool behavior hints.

type ToolCallEnv

type ToolCallEnv = toolconfig.ToolCallEnv

ToolCallEnv is an alias for toolconfig.ToolCallEnv.

type ToolCallPlan

type ToolCallPlan struct {
	RemoteURL         string
	ToolName          string // The tool name to call on the MCP server
	Slug              string
	RequiresOAuth     bool
	TransportType     externalmcptypes.TransportType
	HeaderDefinitions []HeaderDefinition
}

ToolCallPlan contains the execution plan for calling a tool on an external MCP server.

type ToolExtractor

type ToolExtractor struct {
	// contains filtered or unexported fields
}

func NewToolExtractor

func NewToolExtractor(
	logger *slog.Logger,
	db *pgxpool.Pool,
	registryClient *RegistryClient,
) *ToolExtractor

func (*ToolExtractor) Do

type ToolExtractorTask

type ToolExtractorTask struct {
	OrgSlug      string
	ProjectSlug  string
	ProjectID    uuid.UUID
	DeploymentID uuid.UUID
	MCP          ToolExtractorTaskMCPServer
}

type ToolExtractorTaskMCPServer

type ToolExtractorTaskMCPServer struct {
	AttachmentID            uuid.UUID
	RegistryID              uuid.UUID
	Name                    string
	Slug                    string
	RegistryServerSpecifier string
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL